Translation Bundle

Origin & evolution

Bundles are the practical form of the oldest rule in internationalisation: keep the words out of the code. The i18n discipline named at Digital Equipment Corporation in the 1980s externalises strings into resource files addressed by key, and a bundle is one such file scoped to a single locale. Java called them resource bundles; the .NET world used resource files; web stacks settled on JSON or YAML catalogues. The shape differs, the idea holds: one bundle per locale, the same keys across all of them.

The workflow around bundles standardised into three moves. Extract pulls every translatable key from the source into a base bundle. Translate hands that bundle to a translator or service, producing a locale variant🆎VariantGrowthA variant in an A/B testView reference →. Merge folds the returned strings back in, reconciling new keys added since extraction. Modern translation-management platforms automate the round trip, and formats like ICU MessageFormat let a single bundle entry carry the plural and gender variants a language needs🫀NeedUserA user need, pain, desire, or constraintView reference →, so the bundle stays the unit even when individual messages get grammatically complex.

How it works in practice

A product holds 1,200 keys in its base en bundle. To add Japanese, a build step extracts those keys into a ja skeleton and sends it for translation. The returned ja bundle comes back with 1,180 strings filled and 20 left as fallbacks, because new keys landed mid-cycle. The merge step flags those 20 as untranslated. The launch gate is simple: a bundle below full coverage shows English text in the gaps, so the team either finishes the 20 or accepts the fallback before flipping ja-JP live. A specific screen, say checkout, can be wired to its bundle so that screen's readiness is checkable on its own.

Translation bundle vs. its neighbours

• Translation key🗝️Translation KeyLocalisationA translatable string keyView reference → is one entry inside the bundle. The key is the stable identifier; the bundle is the locale-specific collection of all of them. A key lives in many bundles at once, once per locale.
• Locale is what a bundle is for. A bundle has exactly one locale, and the locale's region governs how interpolated dates, numbers, and currency render inside the strings.
• Screen is where a bundle's strings surface. A screen draws its text from a bundle through screen_translated_via_translation_bundleScreentranslated viaTranslation Bundlecross-domain, which lets translation readiness be tracked per surface rather than only per locale.

In the graph

In the Unified Product Graph, a translation bundle is the hub of the localisation region. It connects upward to its locale through locale_translated_via_translation_bundleLocaletranslated viaTranslation Bundlehierarchy, downward to its entries through translation_bundle_contains_translation_keyTranslation BundlecontainsTranslation Keyhierarchy, and outward to the surfaces it serves through screen_translated_via_translation_bundleScreentranslated viaTranslation Bundlecross-domain. That three-way wiring is what makes coverage answerable: walk from a locale to its bundle, count the keys present against the base, and the graph reports exactly how localised that locale is, and which screens are still showing fallback text.