OnlineDocTranslatorGuides

JS Localization: How Translators Fit Into a JavaScript i18n Pipeline

JS localization is the translator-facing stage of a JavaScript i18n pipeline — JSON catalogs, Intl API formatting, ICU plurals, and library handoff explained.

JavaScript localization is where a translator's work meets the engineer's build pipeline — the stage after internationalization, where JSON catalogs, ICU plural blocks, and Intl API arguments must be adapted per locale without breaking the render. This page reframes the JS i18n stack from the translator's desk inside the broader How App Localization Works and What Clients Are Buying process, and defers the engineering-side split to i18n: What Internationalization Means for Translators Producing Localized Builds.

What is JS localization from the translator's side of the desk?

JS localization is the stage of a JavaScript i18n pipeline where translators adapt externalized strings, ICU plurals, and locale-aware formats inside JSON resource bundles so a JS app renders correctly in each locale, after engineers finish internationalization. The translator never edits the component tree. They edit a mirrored catalog per locale ID.

The deliverable is predictable across projects:

  • One JSON resource bundle per target locale, keys and structure identical to the source.
  • ICU plural and select blocks reauthored to the target language's CLDR categories.
  • Intl API arguments preserved byte-for-byte inside the string.
  • Placeholder parity verified against the English source.

How does JS localization differ from JavaScript internationalization (i18n)?

Internationalization is the one-time engineering work that externalizes strings and wires the Intl API. JS localization is the per-locale linguistic work translators repeat for each language, delivered against the JSON or ICU resource bundles i18n produced. The full engineering-side split sits on i18n: What Internationalization Means for Translators Producing Localized Builds.

Who owns which step — engineer, translator, PM?

Three owners split the pipeline cleanly:

  • Engineer — externalizes strings, chooses the i18n library, wires middleware, declares ICU categories.
  • Translator — localizes each JSON catalog, preserves placeholders, reauthors plural blocks per target language.
  • Project manager — runs LQA at $40–$90 per 1,000 words, keeps translation memory in sync across releases, and signs off per-locale delivery.

How does the native JavaScript Intl API shape what translators receive?

The native Intl API formats dates, numbers, currency, plurals, and relative time directly from a locale identifier like en-US or ar-EG, so translators receive source strings with Intl calls already in place. Their job is to preserve the API arguments and translate only the surrounding text.

Which Intl objects appear in source files translators open?

Translators meet six Intl objects most often. Each takes a locale identifier plus an options object the linguist must not alter.

Intl objectWhat it formatsTranslator action
Intl.LocaleLocale identifier parsing (language-script-region)Match filename byte-for-byte
Intl.DateTimeFormatDates and times per calendarPreserve options; translate month/day labels only if explicit
Intl.NumberFormatNumbers, currency, units, percentagesPreserve currency/unit codes; never change style key
Intl.PluralRulesCLDR plural categories per languageAuthor the target language's categories (zero/one/two/few/many/other)
Intl.RelativeTimeFormat"3 days ago", "in 2 hours"Translate output phrase; preserve numeric argument
Intl.ListFormatSerial lists ("A, B, and C")Preserve type and style; translate items only

How does Intl.Locale encode language, region, and script?

Intl.Locale encodes a Unicode BCP 47 locale identifier as language-script-region plus extensions — for example en-Latn-US or zh-Hant-TW. The translator's locale JSON filename must match this identifier byte-for-byte, including hyphen case. A file named es-mx.json will not load against a config expecting es-MX.

Which Intl arguments must the translator preserve verbatim?

Four argument classes survive translation untouched:

  • The locale string itself (en-US, zh-Hant-TW).
  • Options object keys: style, currency, unit, numberingSystem, calendar, notation.
  • Any formatToParts call signature in a template.
  • Named arguments referenced from the string body.

Change any of them and the output format breaks silently per locale.

Which JS localization libraries will translators actually meet?

Translators meet seven JS localization libraries most often: i18next, next-intl, vue-i18n, @angular/localize, Globalize, Polyglot, and Tolgee — each emits a different JSON shape, placeholder syntax, and plural convention the translator must honor.

LibraryResource formatPlaceholderPlural styleCAT risk
i18next / react-i18nextNamespaced JSON{{name}}ICU or suffix keysMedium (Trans tags)
next-intlJSON ICU{name}ICU plural/selectMedium (nested braces)
vue-i18nFlat/nested JSON{count}Pipe-separated formsLow
@angular/localizeXLIFF{$INTERPOLATION}ICU pluralLow
GlobalizeCLDR + message JSON{name}CLDR via Intl.PluralRulesLow
PolyglotFlat JSON%{name}smart_countLow
TolgeeHosted + ICU JSON{name}ICU pluralLow (in-context)

i18next and react-i18next: namespaced JSON and double-curly interpolation

i18next uses namespaced JSON catalogs with double-curly interpolation like {{name}} and a Trans component for inline markup. Translators receive one JSON per namespace per locale and must keep key order and nested structure identical across languages. React-specific pipeline detail sits on React i18n: How Translators Fit Into a React Localization Pipeline.

next-intl: ICU messages, server components, and middleware-aware catalogs

next-intl ships JSON ICU messages consumed inside Next.js server and client components, with middleware deciding which locale JSON loads per request. Translators keep ICU plural and select blocks structurally identical so the App Router build does not throw at render.

Globalize: CLDR-backed formatting with per-feature translation files

Globalize loads Unicode CLDR data per locale and exposes separate translation files for messages, dates, numbers, and currency. Translators work only on the message JSON. CLDR handles date, number, and currency formatting from the locale identifier.

Polyglot and lightweight message libraries

Polyglot is a minimal interpolation-and-plural helper with a flat phrases object and %{name} placeholders. Translators receive a single JSON per locale, no namespacing, and must respect Polyglot's smart_count pluralization syntax. vue-i18n sits in a similar lightweight bracket with flat or nested JSON, named {count} interpolation, and pipe-separated plural forms.

Tolgee: in-context editing as an alternative to raw JSON handoff

Tolgee is both an i18n library and a hosted platform where translators edit strings directly on the live page instead of in en.json, with machine-translation suggestions wired into the editor as post-editing drafts. This removes the triple string → key → component lookup that slows every raw-JSON project.

Node.js server-side localization: Express, i18n-node, and template engines

Node.js server-side JS localization pairs an i18n library (i18n-node, i18next, or next-intl) with a template engine like Mustache or EJS. Translators receive the same JSON catalogs but must watch for template helpers like {{t 'key'}} that compile at render time. For a sibling pairing pattern in a different JS runtime, see Expo Localization: What Translators and Agencies Need to Know About expo-localization.

What do JS localization resource files look like, and which placeholders must translators preserve?

JS localization resource files are overwhelmingly JSON — flat, nested, or ICU — plus occasional JS modules exporting a messages object. Translators preserve three placeholder families: single-curly ICU like {name}, double-curly like {{name}}, and printf-style like %s or %{name}. The full resource-format table sits on Website Localization: What Translators and Agencies Actually Do on the Project.

Flat JSON vs nested JSON vs ICU MessageFormat

Three JSON shapes dominate JS catalogs:

  • Flat JSON — dotted keys like "home.title" at the top level.
  • Nested JSON — actual object hierarchy, read with path syntax.
  • ICU MessageFormat — plural, select, and gender logic wrapped inside the string value itself.

Translators must confirm which pattern the library expects before touching the file.

How ICU plural and select blocks look in a JS catalog

An ICU plural block reads {count, plural, =0 {no items} one {# item} other {# items}}. It must be reproduced structurally in every target locale, using the CLDR plural categories (zero, one, two, few, many, other) that language requires — not a one-to-one copy of English. Arabic needs six categories. Japanese needs one. Russian needs four.

Three placeholder syntaxes break CAT segmentation most often:

  1. ICU select blocks with nested braces.
  2. Trans-component inline tags.
  3. Escaped double-quotes inside JSON values.

Translators tag these as non-translatable or use the CAT tool's placeholder-protection feature before accepting the segment.

How it works

What are the key steps to localize a JavaScript app from the translator's side?

1

Receiving the catalog: en.json, namespaces, and locale IDs

Translators receive one en.json (or a namespaced folder like /locales/en/common.json) as the source. They create a mirror file per locale ID — es-MX.json, ar-EG.json, zh-Hant-TW.json — with identical keys, structure, and Intl options. The locale identifier follows BCP 47: ISO 639-1 language code plus optional ISO 3166-1 country code.

2

Translating strings while preserving keys, placeholders, and comments

Translators change only the value side of each key-value pair. They keep placeholders byte-for-byte and preserve any JSON5 or source-location comments the engineer attached. Those comments resolve the "string → key → component" triple-lookup problem downstream, pointing the linguist to the exact file and line where the string renders.

3

Delivering the file: validation, lint, and build-time checks

Before delivery, four checks run against the per-locale file:

  • JSON lint — valid syntax, no trailing commas, matched braces.
  • ICU compile — every plural and select block parses.
  • Placeholder parity — every {name} and {{name}} in the source exists in the target.
  • Key completeness — no missing keys versus the source.

CI typically fails the PR on any missing key or malformed ICU block. A test build with Pseudo Localization: What Translators Need to Know About i18n Test Builds catches rendering regressions before real locales ship. Before localization starts, five i18n prerequisites must hold in the source build — strings externalized, ICU plurals and gender declared, locale-driven formats, RTL mirroring, and no copy baked into images or canvas — per Application Localization: The Translator's and Agency's Guide.

How does Next.js App Router change JS localization for translators?

The Next.js 13+ App Router moves locale handling into middleware and a [locale] route segment, so translators must know which URL serves which JSON catalog, whether the default locale ships with a /en/ prefix, and how server components stream translations differently from client components.

Middleware-driven locale detection and routing

Next.js middleware reads the Accept-Language header, matches an available locale, and rewrites the request to /[locale]/.... Translators inherit the resulting URL inventory as fixed. Any locale not registered in the middleware config will never load its JSON catalog, no matter how complete the translation file is.

Removing the default-locale prefix from URLs

next-intl requires explicit configuration — localePrefix: 'as-needed' — to strip the /en/ prefix from the default locale. This changes hreflang emission and the URL translators record in their delivery sheet; the prefix is not stripped automatically. The hreflang implications sit on Localization SEO: How Translators Make Localized Pages Rank.

App Router file structure translators should expect

App Router projects place catalogs under /messages/{locale}.json or /locales/{locale}/*.json. The [locale] folder under /app contains page.tsx and layout.tsx. Translators receive the /messages folder, not the component tree, and keys resolve by convention — not by import. A missing key in es-MX.json falls back to the source locale silently unless strict mode is on.

How it works

Manual JSON, AI-generated translations, or hosted platform — which workflow fits the project?

1

When manual JSON editing still wins

Manual JSON editing wins on short-string, high-visibility surfaces — marketing hero copy, legal footers, transactional emails — where translation memory leverage is low and brand voice is high. Translators price this at $0.10–$0.25 per source word with review at $0.04–$0.08 per word.

2

When AI-drafted JSON plus human post-edit is defensible

AI-drafted JSON plus human post-edit is defensible when the catalog exceeds roughly 5,000 segments across 10+ locales and the strings are UI-dense but low-nuance. LQA at $40–$90 per 1,000 words becomes the quality gate that keeps the posture auditable against frameworks like ISO 17100.

3

When Tolgee or a hosted platform earns its subscription

Tolgee and comparable hosted platforms earn their subscription when the DX friction of the triple string → key → component lookup becomes the bottleneck, or when third-party translators must see live context. In-context editing cuts review cycles that would otherwise bounce JSON back through PRs.

4

GraphQL/CMS-driven catalogs for enterprise content

GraphQL and headless CMS integrations manage translation content at scale by storing strings as structured content and querying per locale. This suits marketing-heavy JS apps where editors — not engineers — ship new copy. Translators receive CMS exports rather than git-tracked JSON. Platform-level patterns on How Shopify Localization Works and What It Means for Your Agency and How Webflow Localization Works and What Translators Need to Know contrast with the file-based model, and How to Add i18n to an Astro Site covers content-collection handoff for an adjacent JS stack.

Pricing

How much does JS localization cost, and how do agencies price it?

US agencies price JS localization in four stacked line items: translation at $0.10–$0.25 per source word, review at $0.04–$0.08 per word, LQA at $40–$90 per 1,000 words, and project management at 10–15% of project value, with tooling amortized per project.

Line itemRateScope
Translation$0.10–$0.25 / source wordPer language, per pass
Review$0.04–$0.08 / wordSecond linguist, bilingual check
LQA$40–$90 / 1,000 wordsScorecard against ISO 17100 criteria
Project management10–15% of project valueTM maintenance, release cycles

A 5-language, 50,000-word JS app worked example

A mid-size JS app covering 5 languages and 50,000 words budgets at $25,000–$75,000 end to end. The spread is driven by three variables:

  • Translation-memory leverage from prior releases.
  • Turnaround speed demanded by the release calendar.
  • Whether ICU plural and select blocks need from-scratch authoring per locale.

Where AI pre-translate shifts the cost mix

AI pre-translate shifts cost away from fresh translation and into review ($0.04–$0.08 per word) and LQA ($40–$90 per 1,000 words). The per-word rate falls but the quality-gate line items rise. The end-to-end number for a JS app moves inside the same $25,000–$75,000 band, not below it.

Get a quote

The questions translators and localization PMs ask most about JS localization cluster around library choice, Next.js App Router behavior, scaling catalogs to many languages, and the DX friction of finding a string in code — answered below from the production side.

Frequently asked questions

What is localization in coding?

In software development, localization (l10n) is the process of adapting an application's UI strings, date formats, number formats, and other content so it works correctly for a specific locale or language. It sits downstream of internationalization (i18n), which is the engineering work that makes an app localization-ready — for example, externalizing strings into JSON or PO files. For translators, localization in code means the source strings they translate are pulled from resource files (like en.json), translated, and loaded at runtime. Understanding this pipeline helps translators deliver files that slot directly into a developer's build.

Do I have to write translations for all languages manually in JSON files?

You don't have to write every translation manually from scratch, but a qualified human translator (or a first-draft tool followed by a translator) must review every string before it ships. Most JS i18n pipelines store translations in per-locale JSON files (e.g., fr.json, de.json), one file per language. Machine translation or AI tools like a first-draft SaaS can populate those files quickly, but certified or professional-grade output still requires a translator to verify accuracy, tone, and completeness. Agencies typically own the QA step that bridges the raw JSON output and the final approved file.

What's the best way to implement localization in Next.js — CMS or ChatGPT?

Neither a headless CMS nor ChatGPT alone is a complete localization solution — the best approach combines a structured i18n library (like next-intl or next-i18next) with professional translator review. A CMS is useful for marketing copy that changes frequently; a code-based JSON workflow is better for UI strings. AI tools, including ChatGPT, can generate fast first drafts that translators then post-edit, which is exactly the model certified translation pipelines are adopting. The critical point for agencies is that no AI output should be delivered as a finished certified translation without a qualified human reviewer signing off.

How do I set up internationalization in Next.js 15 app router?

In Next.js 15 with the App Router, the standard approach is to wrap your app with a locale-aware layout using a [locale] dynamic segment and a middleware file that detects and redirects to the correct locale. Libraries like next-intl provide a useTranslations() hook and a server-side getTranslations() function that load strings from per-locale JSON files at build or request time. You define supported locales in your next.config.js (or next.config.ts), and the middleware handles routing. For translation teams, the output is a set of JSON resource files — one per locale — that translators populate and agencies review before deployment.

Which i18n library works best with Next.js 13+ app router?

next-intl is widely regarded as the best fit for Next.js 13+ App Router because it was purpose-built for React Server Components and supports both server-side and client-side translation loading. next-i18next remains popular for Pages Router projects but requires more configuration to work with App Router. Paraglide JS (by inlang) is a newer, type-safe alternative worth evaluating. For translation teams, the choice of library determines the file format (usually JSON) and the key structure they'll receive — so agencies should confirm the format with the dev team before starting translation work.

How do I find a UI string in code when using a localization file?

Search your codebase for the translation key used in the component, then look up that key in the relevant locale JSON file. For example, if a component calls t('checkout.submitButton'), search for checkout.submitButton in your en.json (or equivalent source-language file) to find the original string. Most editors support global search across files (Ctrl+Shift+F in VS Code). For translators working outside the codebase, a translation management system (TMS) or a shared spreadsheet keyed by the same IDs gives equivalent visibility without needing code access.

How do I format numbers in JavaScript?

Use the built-in Intl.NumberFormat API to format numbers according to a specific locale in JavaScript. For example, new Intl.NumberFormat('de-DE').format(1234567.89) outputs '1.234.567,89' — correct for German locale conventions. This matters directly for translators and localization engineers because numeric formatting (decimal separators, thousands separators, currency symbols) varies by locale and should never be hardcoded. The Intl API covers number, currency, and percentage formatting and is supported in all modern browsers and Node.js without any external library.

Related