Locize Sync
Apps & Automationlocize-syncLocize Sync is an Agent Skill for apps & automation published in the Opentrons/opentrons repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Opentrons/opentrons/blob/HEAD/.cursor/skills/locize-sync/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/locize-sync, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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 viauv 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/intoapp/before syncing, then unconsolidates back
- Primary:
-
Authentication —
LOCIZE_API_KEYandLOCIZE_PROJECT_IDenv vars (local.envor 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
- Locize CLI: https://github.com/locize/locize-cli
- Locize Web Interface: https://locize.app
- Script:
scripts/locize_sync.py