# How to Sync Locale Files in Escrcpy: A Complete Guide

> Sync locale files in escrcpy effortlessly with the pnpm lang-sync command. This guide shows how to standardize translations using the Node.js script for efficient i18next-json-sync.

- Repository: [viarotel-org/escrcpy](https://github.com/viarotel-org/escrcpy)
- Tags: how-to-guide
- Published: 2026-09-10

---

**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`](https://github.com/viarotel-org/escrcpy/blob/main/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`](https://github.com/viarotel-org/escrcpy/blob/main/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`](https://github.com/viarotel-org/escrcpy/blob/main/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`](https://github.com/viarotel-org/escrcpy/blob/main/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`](https://github.com/viarotel-org/escrcpy/blob/main/desktop/electron/resources/extra/common/locales/zh-CN.json) and insert your new key:

```json
{
  "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:

```bash
pnpm lang-sync

```

Alternatively, use npm or yarn:

```bash
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`](https://github.com/viarotel-org/escrcpy/blob/main/en-US.json)) to confirm the new key appears with an empty value ready for translation:

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

```

## Understanding the Sync Configuration

The actual implementation in [`scripts/lang-sync.js`](https://github.com/viarotel-org/escrcpy/blob/main/scripts/lang-sync.js) configures the sync utility as follows:

```javascript
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`](https://github.com/viarotel-org/escrcpy/blob/main/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`](https://github.com/viarotel-org/escrcpy/blob/main/zh-CN.json) in `desktop/electron/resources/extra/common/locales/`
- **Script location** is [`scripts/lang-sync.js`](https://github.com/viarotel-org/escrcpy/blob/main/scripts/lang-sync.js), configured via [`package.json`](https://github.com/viarotel-org/escrcpy/blob/main/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`](https://github.com/viarotel-org/escrcpy/blob/main/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`](https://github.com/viarotel-org/escrcpy/blob/main/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`](https://github.com/viarotel-org/escrcpy/blob/main/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.