Localization

Localess is built for global teams that need to ship in multiple languages. It provides two complementary localization capabilities that solve different problems. Understanding which one to reach for — and when to use both — is the starting point for any multilingual project.

Translation Manager

What it is

Translation Manager is Localess's key–value string management system for web application UI copy. Think of it as a hosted, editor-friendly replacement for local i18n JSON files — the kind you would normally manage with a library like i18next, react-intl, or Angular's built-in i18n module.

Instead of committing JSON files to your repository, you manage strings in the Localess UI and pull them at runtime via the API. The API returns a flat key–value map that drops straight into any i18n library.

When to use it

Use Translation Manager when you need to translate application UI strings — labels, error messages, tooltips, button copy, navigation items — that live in your codebase rather than in content documents.

Good candidates:

• "nav.home" → "Home" / "Accueil" / "Startseite"
• "errors.required" → "This field is required" / "Ce champ est obligatoire"
• "common.submit" → "Submit" / "Envoyer" / "Absenden"

Not a good fit: long-form editorial content (articles, landing pages, product descriptions). Use Content Translation for those.

How it works

1. Navigate to Translations in the side menu.
2. Click + Add Translation and give the entry a unique ID — for example, nav.home or errors.required.
3. Add the value for your default locale.
4. Enable Auto-translate to request machine translations for all other configured locales automatically (powered by Google Cloud Translation or DeepL).
5. Click Publish when you are ready to make the strings available to production consumers.

Translations follow the same Draft & Publish model as content: saved changes are immediately available with ?version=draft, and published changes are available to production without a version parameter.

Translation Status

Localess tracks completeness automatically:

Use the Status filter in the toolbar to find strings that need attention before your next release.

Code example — fetching via SDK

// @localess/client
const translations = await client.getTranslations('en');
// { "nav.home": "Home", "errors.required": "This field is required", ... }

// Pass directly to i18next or any other i18n library
i18next.addResourceBundle('en', 'translation', translations);

# Pull translations to a local JSON file using the CLI
npx localess translations pull en --path ./locales/en.json

The flat JSON format is compatible with i18next, react-intl, LinguiJS, Vue I18n, Angular's $localize, and any other library that accepts a key–value map.

Content Translation

What it is

Content Translation is the per-field multilingual capability built into Localess content documents. Every document can store independent values for each field in every locale you have configured. Editors switch between locales inside the same document editor and fill in each language version independently.

This is different from Translation Manager: you are not managing short UI strings — you are managing full structured content documents (pages, articles, product listings) where each field (title, body, image alt text, CTA label) needs a locale-specific value.

When to use it

Use Content Translation when you need to translate structured content documents — anything shaped by a Schema in Localess.

Good candidates:

• A blog article that has a different title, body, and metadata in each language
• A product listing where the description, features, and pricing copy differ by locale
• A landing page where headlines and body copy are fully translated rather than just substituted

Not a good fit: short application UI strings that do not belong in a CMS document. Use Translation Manager for those.

How it works

1. Open a document in the Content editor.
2. In the right panel, use the Locale dropdown to select the locale you want to edit.
3. Fill in all fields for that locale. Fields that have not been filled in for a locale remain empty in the API response for that locale.
4. Save the locale's content, then switch to the next locale and repeat.
5. When all locales are ready, click Publish to promote the document to the published state for all locales at once.

Each locale's values are stored independently. Saving one locale does not overwrite another.

Fetching content for a specific locale

Pass the locale parameter when fetching a document. Localess returns the field values for that locale:

// Fetch the English version
const enContent = await client.getContentBySlug<Article>('blog/my-post', {
  locale: 'en',
});

// Fetch the French version of the same document
const frContent = await client.getContentBySlug<Article>('blog/my-post', {
  locale: 'fr',
});

// Fetch the draft version while previewing
const draft = await client.getContentBySlug<Article>('blog/my-post', {
  locale: 'de',
  version: 'draft',
});

How locales are configured

Locales are configured at the Space level in Settings → Locales. Every content document and translation entry automatically gains a slot for each configured locale. Add a locale once; it appears everywhere.

Using Both Together

Most multilingual applications use both capabilities at the same time:

• Translation Manager supplies the i18n namespace for UI chrome — navigation, buttons, form labels, error messages.
• Content Translation supplies the locale-specific body content — articles, landing pages, product descriptions.

// In a Next.js server component: load both in parallel
const [translations, page] = await Promise.all([
  client.getTranslations(locale),
  client.getContentBySlug<Page>('home', { locale }),
]);

This separation keeps application copy and editorial content in the right system: developers own the key structure in Translation Manager; editors own the narrative in Content documents.