# Localization System Architecture Relevant source files - [.github/workflows/update-pr.yaml](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/.github/workflows/update-pr.yaml) - [crowdin.yml](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/crowdin.yml) - [readme.md](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/readme.md?plain=1) ## Purpose and Scope This document describes the technical architecture of the localization system used in the front-web-platform-locales repository. It covers the organization of localization files, the translation management workflow, and how the localization system integrates with the main front-web-platform repository. For information about the translation workflow process, see [Translation Workflow](/content/FrontFin/front-web-platform-locales/1.2-translation-workflow/index.html). For details on supported languages, see [Multi-Language Support](/content/FrontFin/front-web-platform-locales/1.3-multi-language-support/index.html). ## Architecture Overview The localization system is designed to provide multi-language support for the Mesh Connect platform through a maintainable, scalable architecture with automated synchronization between repositories. ``` front-web-platform Automation Translation Service front-web-platform-locales Source for translations Generates translations Configures Updated translations trigger Creates PR with updates Provides translations to en/catalog.json (Source) Translated Files (es, ru, tr, etc.) crowdin.yml Crowdin Translation Platform GitHub Action: update-pr.yaml packages/localization/locales i18next Implementation ``` Sources: [.github/workflows/update-pr.yaml](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/.github/workflows/update-pr.yaml) [crowdin.yml](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/crowdin.yml) [readme.md](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/readme.md?plain=1) ## File Structure and Organization The localization system uses a JSON-based file structure with a primary English source catalog and corresponding translated catalogs for other languages. ``` Repository Root en/ es/ ru/ tr/ Other Language Folders catalog.json (Primary Source) catalog.json catalog.json catalog.json crowdin.yml .github/workflows/ update-pr.yaml ``` Sources: [crowdin.yml](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/crowdin.yml) ### JSON Catalog Structure The localization files follow a consistent structure where each key-value pair represents a translatable string. The English catalog serves as the source of truth. | Component | Description | | --- | --- | | JSON keys | Unique identifiers for text strings | | HTML tags | Preserved using numeric indices (e.g., `<1>text`) | | Variables | Maintained using double curly braces (e.g., `{{variable}}`) | Sources: [readme.md9-13](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/readme.md?plain=1#L9-L13) [readme.md25-37](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/readme.md?plain=1#L25-L37) ## Translation Management System The repository uses Crowdin as the translation management platform, which handles both automatic AI-based translations and human proofreading. ``` Integration Workflow Crowdin Workflow Developer Workflow Push to main Changes approved Create PR Merge PR Trigger update-pr.yaml workflow Add/Update English Source Strings Update Source in Crowdin AI Translation Human Proofreading Push to l18n_main branch Review/Verify Translations Updated l10n Repository Create PR in front-web-platform ``` Sources: [readme.md3-4](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/readme.md?plain=1#L3-L4) [.github/workflows/update-pr.yaml3-7](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/.github/workflows/update-pr.yaml#L3-L7) ### Crowdin Configuration The Crowdin integration is configured through `crowdin.yml`, which defines: 1. Hierarchy preservation (`preserve_hierarchy: 1`) 2. Source files location (`/en/*.json`) 3. Translation output path (`/%two_letters_code%/%original_file_name%`) Sources: [crowdin.yml1-4](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/crowdin.yml#L1-L4) ## Automated Synchronization System The repository employs GitHub Actions to automatically synchronize translation updates with the main front-web-platform repository. ``` "front-web-platform""GitHub Actions""front-web-platform-locales""Translator/Crowdin""front-web-platform""GitHub Actions""front-web-platform-locales""Translator/Crowdin"Changes merged to main branchPR targeted at packages/localization/localesUpdate translationsTrigger workflow on push to mainCheckout front-web-platform repositoryGet latest translations from locales repositoryCreate PR with updated translationsReview and merge translation updates ``` Sources: [.github/workflows/update-pr.yaml3-61](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/.github/workflows/update-pr.yaml#L3-L61) ### GitHub Action Workflow Details The `update-pr.yaml` workflow: 1. Triggers on push to main branch or manual dispatch 2. Checks out the front-web-platform repository 3. Updates the submodule at `./packages/localization/locales` with the latest translations 4. Creates a pull request with the changes, assigning the Frontend team as reviewers This automation ensures that translation changes are consistently propagated to the main application codebase. Sources: [.github/workflows/update-pr.yaml9-61](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/.github/workflows/update-pr.yaml#L9-L61) ## Common Translation Issues The localization system is designed to handle special formatting elements, but certain common issues can occur: ### HTML Tag Preservation Translation must maintain the correct tag structure: - English: "Some <1>important string." - Correct translation: "Alguna cadena <1>importante." - Incorrect: "Alguna cadena <1>importante." ### Variable Placeholder Preservation Variables must be maintained exactly as in the source: - English: "Some {{one}} {{two}} string." - Correct translation: "Algunas cadenas {{one}} {{two}}." - Incorrect: "Algunas {one} {{dos}} cuerdas." Sources: [readme.md5-37](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/readme.md?plain=1#L5-L37) ## Integration with Front Web Platform ``` front-web-platform Repository front-web-platform-locales Repository Application Components packages/localization/ Synchronized via GitHub Action Provides translation data Makes translations available via Used by Translation Source Files locales/ (Git Submodule) i18n Configuration React Components Translation Hooks ``` Sources: [.github/workflows/update-pr.yaml41-45](https://github.com/FrontFin/front-web-platform-locales/blob/967df441/.github/workflows/update-pr.yaml#L41-L45) ## Summary The localization system architecture: 1. Uses a structured JSON format with English as the source language 2. Employs Crowdin for translation management (both AI and human translations) 3. Maintains formatting elements like HTML tags and variables 4. Automates synchronization between repositories via GitHub Actions 5. Integrates with the main front-web-platform repository as a submodule This architecture ensures efficient management of translations across multiple languages while maintaining consistency in the application interface.