Localization System Architecture

Relevant source files

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. For details on supported languages, see Multi-Language Support.

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 crowdin.yml readme.md

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

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</1>)
Variables Maintained using double curly braces (e.g., {{variable}})

Sources: readme.md9-13 readme.md25-37

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 .github/workflows/update-pr.yaml3-7

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

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

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

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</1> string."
  • Correct translation: "Alguna cadena <1>importante</1>."
  • 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

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

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.