How to Sync Locale Files in Escrcpy: A Complete Guide

To sync locale files in escrcpy, run pnpm lang-sync from the project root to execute the Node.js script at scripts/lang-sync.js, which automatically standardizes all translation files against the primary Chinese (zh-CN) locale using i18next-json-sync.

Escrcpy, the open-source Android screen mirroring application from viarotel-org, manages UI translations through JSON files that can drift out of alignment when developers add or modify features. The repository includes a purpose-built synchronization mechanism that ensures every language file maintains identical key structure, ordering, and formatting without manual intervention.

Where Locale Files Are Stored

Escrcpy stores all translatable strings as JSON files in desktop/electron/resources/extra/common/locales/. The project supports multiple languages including English (en-US), Russian (ru-RU), Japanese (ja-JP), and Arabic (ar), alongside the primary Chinese Simplified (zh-CN) reference file.

Each JSON file contains flat key-value pairs mapping translation identifiers to localized strings. When contributors introduce new UI elements or modify existing text, these files can accumulate missing keys, inconsistent ordering, or formatting variations that the sync script resolves automatically.

How the Sync Script Works

The synchronization logic resides in scripts/lang-sync.js. This script imports the i18next-json-sync library and configures it to treat zh-CN as the primary language source.

According to the source code in package.json, the script is exposed through the npm script "lang-sync": "node ./scripts/lang-sync.js". When invoked, the tool performs four critical operations on every locale file:

• Key alignment: Reorders all keys to match the primary zh-CN.json exactly
• Missing key insertion: Adds empty strings for any keys present in zh-CN but absent from target locales
• Orphan removal: Deletes keys that exist in secondary languages but not in the primary file
• Format enforcement: Applies 2-space indentation, LF line endings, and ensures a final newline

The script explicitly excludes node_modules directories through the excludeFiles: ['**/node_modules/**'] configuration parameter.

Step-by-Step Syncing Process

Adding or Modifying Keys

Always edit the primary locale file first. Open desktop/electron/resources/extra/common/locales/zh-CN.json and insert your new key:

{
  "mirroring.controls.fullscreen": "全屏模式"
}

Save the file after making changes. Do not manually edit secondary locale files during this process.

Running the Sync Command

Execute the synchronization using your preferred package manager:

pnpm lang-sync

Alternatively, use npm or yarn:

npm run lang-sync

# or

yarn lang-sync

The terminal output indicates which files were modified. The script automatically updates all *.json files in the locales directory to match the zh-CN structure.

Verifying Changes

Check any secondary locale file (such as en-US.json) to confirm the new key appears with an empty value ready for translation:

{
  "mirroring.controls.fullscreen": ""
}

Understanding the Sync Configuration

The actual implementation in scripts/lang-sync.js configures the sync utility as follows:

import sync from 'i18next-json-sync'

// @ts-ignore
sync.default({
  excludeFiles: ['**/node_modules/**'],
  files: 'desktop/electron/resources/extra/common/locales/*.json',
  primary: 'zh-CN',
  lineEndings: 'LF',
  space: 2,
  finalNewline: true,
})

This configuration ensures cross-platform consistency. The files glob pattern matches all JSON files in the locales directory, while primary: 'zh-CN' establishes the source of truth. The space: 2 setting maintains readable formatting across the codebase.

The AGENTS.md file in the repository root references this synchronization workflow, documenting it as a required step after editing locale keys to maintain translation integrity.

Summary

• Run pnpm lang-sync to synchronize all locale files against the primary Chinese translation
• Primary source is always zh-CN.json in desktop/electron/resources/extra/common/locales/
• Script location is scripts/lang-sync.js, configured via package.json
• i18next-json-sync handles key ordering, missing key insertion, and cleanup automatically
• Manual editing of secondary locale files is unnecessary and discouraged; the tool propagates changes from zh-CN

Frequently Asked Questions

What command syncs locale files in escrcpy?

Run pnpm lang-sync from the repository root. This executes the Node.js script defined in package.json that processes all JSON files in the locales directory using i18next-json-sync. The command works identically across npm, pnpm, and yarn package managers.

Which language serves as the primary reference for translations?

Chinese Simplified (zh-CN) is the primary language. The sync script treats zh-CN.json as the source of truth, aligning all other locale files to its key structure and order. Contributors should always add new translation keys to this file first before running the sync.

Where are the locale files located in the escrcpy codebase?

All translation files reside in desktop/electron/resources/extra/common/locales/. This directory contains individual JSON files for each supported language (zh-CN.json, en-US.json, ru-RU.json, etc.), which the synchronization script scans automatically via the glob pattern configured in scripts/lang-sync.js.

What happens if locale files become out of sync?

Missing keys in secondary languages appear as empty strings after running the sync, while extra keys not present in zh-CN get removed. The UI will not display missing translation errors at runtime because the sync ensures every key exists across all language files, even if some values remain empty pending translation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}