| name | locize-sync |
| description | Locize i18n synchronization workflow for pushing and downloading translations in the Opentrons monorepo. Use when working with locize_sync.py, localization files in app/src/assets/localization/ or components/src/assets/localization/, or syncing translations. |
Locize Synchronization Instructions
Overview
The Locize synchronization system manages internationalization (i18n) for the Opentrons monorepo. A unified Python script syncs localization files between the codebase and Locize cloud service.
Dry-Run Mode: All commands support --dry-run to preview actions without making changes.
Architecture
Core Components
-
Sync Script (scripts/locize_sync.py) — Python script executed via uv run, two actions:
push-local: Upload local English and Chinese translations to Locizedownload-remote: Download English and Chinese translations from Locize
-
Localization Files
- Primary:
app/src/assets/localization/ — main application translations
- Secondary:
components/src/assets/localization/ — shared component translations
- English (
en) is the source of truth; Chinese (zh) is downloaded from Locize. Chinese (zh) files may be invisible to agents because of the repo's ignore rules.
- The script consolidates files from
components/ into app/ before syncing, then unconsolidates back
-
Authentication — LOCIZE_API_KEY and LOCIZE_PROJECT_ID env vars (local .env or GitHub Actions secrets)
Commands
Push Local Translations (Source of Truth)
uv run scripts/locize_sync.py push-local
Pushes English translations from repo to Locize. The script consolidates components/ JSON into app/, runs locize-cli sync, then unconsolidates and formats with make format-js.
When to use: After updating local English/Chinese strings, before handing to translators, to resolve drift.
Download Remote Translations (Overwrite Local)
uv run scripts/locize_sync.py download-remote
Downloads English and Chinese translations from Locize, overwriting local files. Consolidates, downloads, unconsolidates, and formats.
When to use: After translators finish work, prior to release, to align with remote content.
Dry-Run Mode
uv run scripts/locize_sync.py push-local --dry-run
uv run scripts/locize_sync.py download-remote --dry-run
Performs consolidation/unconsolidation to validate workspace, displays exact commands, but makes no remote changes.
Lint and Format the Script
uvx ruff check --fix scripts/locize_sync.py && uvx ruff format scripts/locize_sync.py
CI/CD Integration
Store credentials in repository secrets: LOCIZE_API_KEY, LOCIZE_PROJECT_ID.
References
