Translation Manager vs Content Translation: Two Ways Localess Handles i18n

There is a detail that trips up almost every developer evaluating a headless CMS for a multilingual app: "localization" and "content translation" are not the same problem. They look similar from the outside — you have text, you need it in multiple languages — but they require different data structures, different workflows, and different tooling.

Most CMSes solve one of these problems and awkwardly stretch it to cover the other. Localess ships two purpose-built systems: the Translation Manager for UI strings, and Content Translation for structured content documents. Understanding the difference will save you hours of confusion when you start an integration.

The Two Problems

Problem 1: UI string management

Your app has button labels, error messages, navigation items, toast notifications, form placeholders. These are typically short strings, keyed by an identifier (common.submit, nav.home, errors.required), and managed with libraries like i18next, react-i18next, or Angular's TranslateModule.

The challenge: these strings live in JSON files committed to your repository. Updating a label requires a developer, a PR, and a deploy. For a string that says "Get started", that is a lot of infrastructure.

Problem 2: Structured content localization

Your marketing site has a landing page with a headline, body text, a hero image, and an embedded button component. These are rich, nested documents — not flat key-value pairs. Each language needs its own version of the headline, but may share the same image. The structure varies by locale: German copy is longer, Japanese layout needs different spacing assumptions.

Managed with the same key-value map as your button labels? That gets painful fast.

Translation Manager — for UI Strings

The Translation Manager is Localess's answer to scattered i18next JSON files. You create translation entries with a unique key (common.submit, nav.home), write values for each locale, and optionally trigger an AI-assisted first-pass translation via Google Cloud Translation or DeepL. The result is available via the API as a flat JSON map — exactly the format that i18next, react-i18next, and Angular's TranslateModule expect.

import { LocalessClient } from '@localess/client';

const client = new LocalessClient({
  spaceId: 'your-space-id',
  token: process.env.LOCALESS_API_TOKEN,
});

// Returns: { "common.submit": "Submit", "nav.home": "Home", ... }
const translations = await client.getTranslations('en');

You can also pull translations to local JSON files for static builds or offline use:

npx @localess/cli translations pull en --path ./locales/en.json

This makes Localess a drop-in translation source for any app that already uses a key-based i18n library. Your frontend i18n code does not change — only the source of truth for the strings does.

What Translation Manager gives you on top of a plain JSON file:

• Status tracking per locale — Translated / Partially Translated / Untranslated, computed automatically
• Auto-translate — configure Google Cloud Translation or DeepL once; new entries get a first-pass translation on creation
• Label-based grouping — organize strings by feature area (onboarding, errors, navigation) and filter in the UI
• Draft/Published states — stage translation work in progress before it hits production consumers
• No build step — publish and strings are live via CDN in approximately 30 seconds

Content Translation — for Structured Documents

Content Translation works at the document level. When you create a content document in Localess, it is shaped by a Schema — a typed definition of what fields it contains. Each locale gets its own version of those fields.

This means a landing page document can have:

• headline (TEXT) — different per locale
• body (RICH_TEXT) — different per locale
• heroImage (ASSET) — shared across locales or overridden per locale
• ctaButton (SCHEMA) — a nested component block, itself localizable

In the editor, you select a locale from a dropdown and fill in the fields for that language. Save → preview in draft mode → Publish when ready. Each locale is stored independently and served independently via the API.

// Fetch the English version of a landing page
const page = await client.getContentBySlug<LandingPage>('marketing/home', {
  locale: 'en',
  resolveReference: true,
  resolveLink: true,
});

// Same document, German locale
const pageDe = await client.getContentBySlug<LandingPage>('marketing/home', {
  locale: 'de',
  resolveReference: true,
  resolveLink: true,
});

TypeScript types for your schemas are generated by the CLI, so you get type-safe access to document fields without manually writing interfaces:

npx @localess/cli schema export --output ./types/localess.ts

When to Use Which

In practice, most apps use both. The Translation Manager handles the UI string layer — everything that lives in your i18next JSON files today. Content Translation handles the page and content layer — everything that would otherwise live in a database or a structured CMS document.

The Separation Is the Feature

Most headless CMSes that claim to support "localization" are doing one of two things: bolting on field-level locale variants for structured content with no real story for UI strings — or stretching a flat key-value store to cover structured content through naming conventions (landing.hero.headline), which collapses the moment content gets nested.

Localess treats these as distinct systems because they have distinct requirements. The Translation Manager speaks the language of i18next and delivers flat JSON. Content Translation speaks schemas, typed fields, and per-locale document editing. Each is designed for the problem it solves.

If you are building a multilingual app that has both a UI layer and a content layer — which most apps do — having two dedicated systems is not complexity. It is clarity.

Getting Started

Both systems are available in every Localess Space. Start with the TypeScript SDK for server-side access:

npm install @localess/client

For React and Next.js App Router, reach for @localess/react — it wraps @localess/client with React hooks and React Server Component support:

npm install @localess/react

Full setup guides and API reference are in the Localess documentation.