global-i18n-sync

Production-oriented CLI to sync Android (strings.xml), iOS (Localizable.strings), and Web (nested JSON) with the Global Localization Service HTTP API.

Requirements

• Node.js 18+
• API user with developer or company_admin role (for POST /translations/bulk and GET /translations)

Install

npm install -g global-i18n-sync
# or in a project:
npx global-i18n-sync init

From this repository:

cd i18n-sync
npm install
npm run build
npm link   # optional: global global-i18n-sync command

Configuration

cd your-app
global-i18n-sync init   # creates i18n.config.cjs

Set credentials (in order of precedence):

• I18N_SYNC_TOKEN environment variable
• .i18n-sync/token (prompted on init, push, or pull)
• apiToken in i18n.config.cjs

Default API URL: https://localize-api.lcx.com (override with I18N_SYNC_API_URL).

Commands

| Command | Description | |--------|-------------| | global-i18n-sync init | Write i18n.config.cjs template | | global-i18n-sync push | Parse local files, diff vs .i18n-sync/cache.json, POST /translations/bulk | | global-i18n-sync pull | Merge remote translations into local locale files (see below) | | global-i18n-sync version-remote | GET /admin/system/version |

All commands accept --cwd <dir> (or -C).

Pull behavior (merge)

Pull targets are resolved from GET /languages for the app tied to your API key (enabled languages only). Disabled languages (e.g. Russian Off in the admin UI) are not pulled. English / source locale is always excluded.

Optional targets: ["de"] in config narrows the pull to a subset of enabled languages (useful for CI). Omit targets to pull all enabled app languages.

Pull only processes those resolved targets. Other locale folders on disk are not scanned or modified.

| Scenario | Behavior | |----------|----------| | Base only (values/strings.xml) | Creates values-{lang}/strings.xml (and iOS/web equivalents) for each target | | Complete local translation file | Merge-only: keeps existing non-empty local values; skips write if nothing changed | | Base has untranslated keys | Omits keys with no translation (no empty placeholders, no English fallback) | | Many locales on disk, few in targets | Only configured targets are updated |

Merge rules per key:

1. Local non-empty → keep local
2. Else API non-empty → use API text
3. Else → omit from locale file

Non-translatable resources

| Platform | Rule | |----------|------| | Android | translatable="false" — excluded from push and pull (stays in base values/ only) | | iOS .xcstrings | shouldTranslate: false — excluded | | iOS .strings / Web JSON | No standard flag (N/A) |

Batching (large projects)

Push: sends keys in chunks via bulkChunkSize (default 200). Retries on timeout/5xx.

| Config / env | Default | Purpose | |--------------|---------|---------| | bulkChunkSize / I18N_SYNC_BULK_CHUNK_SIZE | 200 | Keys per POST /translations/bulk | | apiTimeoutMs / I18N_SYNC_TIMEOUT_MS | 180000 | HTTP timeout | | push.useMaxSyncKeys | false | When true, cap keys with maxSyncKeys (dev) |

Pull: fetches translations in pages via pull.pullChunkSize (default 500) using GET /translations?offset=&limit=.

| Config / env | Default | Purpose | |--------------|---------|---------| | pull.pullChunkSize / I18N_SYNC_PULL_CHUNK_SIZE | 500 | Keys per API page | | pull.useMaxSyncKeys | false | When true, cap keys with maxSyncKeys (dev) | | I18N_SYNC_MAX_KEYS | — | Overrides both push/pull caps |

Push behavior

• Merges Android / iOS / Web paths; default conflict policy web-wins
• Sends only keys whose SHA-256 hash of baseText changed vs .i18n-sync/cache.json
• Skips Android/iOS non-translatable resources at parse time

Development

npm run build
npm test

License

Same as the parent project.