Internationalization (I18n) Overview and the Starling Platform

Internationalization Overview

Deng Minjie, core developer of the ByteStarling Internationalization Platform, introduces the fundamentals of internationalization (I18n), localization (I10n) and globalization (g11n), explaining how decoupling software from specific languages and regions simplifies production of regional versions.

Internationalization Objects

Websites and apps require adaptation in four main areas: static text, dynamic text, code comments, and multimedia resources. Static text is predefined and can be uploaded to Starling via direct upload or Excel files. Dynamic text, such as user‑generated comments, is collected at runtime and treated as static text after translation.

Code comments that contain multilingual information should also be internationalized to aid understanding and compliance. Documentation (e.g., manuals, agreements) and multimedia assets (images, fonts, audio) need translation, often involving professional translators or the Starling platform.

Internationalization Process

In theory, a single I18n‑compatible framework suffices, but without a standard framework, custom mapping mechanisms lack consistency, especially for locale‑specific pluralization, numbers, and currencies. Developers can inspect the global Intl object in the browser console.

Evolution of Internationalization

Manual Stage : Developers extract text manually into files (usually Excel), upload to Starling, wait for translation, and integrate the results back into the codebase.

Dynamic Delivery : Starling introduces dynamic delivery, allowing SDK‑based runtime fetching of translated strings, decoupling development from translation.

Tooling Era : Automation tools (CLI, VSCode extensions, In‑Context browser plugin) eliminate manual collection and upload, providing monitoring, alerts, and streamlined workflows.

Standardized Ops : I18nOps standardizes the workflow, visualizes the entire process, supports secondary modifications, and ensures consistent quality regardless of developers' i18n experience.

Starling Platform

Projects are created on Starling, where a "space" stores all translatable strings. Tasks linked to spaces synchronize additions, modifications, and deletions of text. After review, texts are published by selecting language ranges and version numbers, making the latest translations available for developers.

Stakeholder Concerns

Product/UX/QA : Verify that localized text meets regional requirements, track translation progress, and ensure completeness.

Design : Check UI layout for different languages, ensure length adaptation, and integrate translation platforms.

Testing : Ensure correct language rendering and detect any language‑mixing issues.

Development Guidelines

Language‑Region Codes : Follow BCP‑47 tags (e.g., en-US , zh-CN ) to specify language and region.

Mapping Relationships : Define source language (e.g., Chinese) and target translation languages; use unique keys to avoid ambiguity.

ICU Message Format : Combine literal strings with placeholders inside {} to handle gender, pluralization, numbers, dates, etc.

ECMA‑402 Intl API : Provides locale‑aware string comparison, number formatting, and date/time formatting for JavaScript.

Common front‑end frameworks such as starling_intl and react-intl implement these standards.

Dynamic Text Handling

For runtime‑generated text (e.g., comments, product names), tag the nodes for dynamic translation, optionally using machine translation or backend APIs to fetch accurate translations.

Efficiency Tools

VSCode extensions enable one‑click upload, translation, and comment localization. CLI tools assess i18n coverage across repositories and provide bulk replacement commands.

Key Management

Keys can be defined by developers (aligning with code rhythm) or by product teams (accelerating workflow and adding module context). Quality of keys and timing of their creation impact overall i18n efficiency.

Translation Modes

Post‑translation : Development first, localization later; suitable for low‑urgency or small‑scale projects.

Pre‑translation : Development and localization run in parallel; ideal for large‑scale, multi‑language projects with long translation cycles.

I18nOps Standardization

I18nOps aggregates i18n data per repository, performs static text extraction, evaluates code quality, and offers automated key generation, dynamic text filtering, and one‑click translation. It visualizes coverage metrics (code, comment, translation) and supports an "internationalization work‑order" mode to streamline the entire process.

References

[1] ISO 639 language codes – https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

[2] Ruanyifeng’s explanation – http://www.ruanyifeng.com/blog/2008/02/codes_for_language_names.html

[3] ICU Message Format – https://starling.bytedance.net/open/content/9163/111707

[4] ICU Formatting Messages – http://userguide.icu-project.org/formatparse/messages

[5] ICU Online Test – https://devpal.co/icu-message-editor/?data=I%20have%20%7Bnum%2C%20plural%2C%20one%7B%7Bnumber%7D%20%23%20apple%7D%20other%7B%23%20apples%7D%7D%2Cbut%20it%27s%20too%20small%0A

[6] ECMA‑402 – https://tc39.es/ecma402/

[7] MDN Intl documentation – https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl

[8] react‑intl – https://formatjs.io/docs/getting-started/installation/