locize-sync

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

1. Sync Script (scripts/locize_sync.py) — Python script executed via uv run, two actions:

   • push-local: Upload local English and Chinese translations to Locize
   • download-remote: Download English and Chinese translations from Locize

2. 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

3. 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

• Locize CLI: https://github.com/locize/locize-cli
• Locize Web Interface: https://locize.app
• Script: scripts/locize_sync.py