Localization of Filters

September 15, 2026 ยท View on GitHub

The /locales directory contains translations for filters, groups, and tags.

Requirements

  1. For third-party filters, only REQUIRED_LOCALES should be 100% complete.

  2. For AdGuard filters, all locales are required, meaning they must be 100% translated.

Integration with Translation Service

It's essential to import strings from the service before exporting them, as some changes may be lost otherwise.

  1. Install dependencies in the root directory:

    yarn install

  2. Download the Latest Translations:

    To import strings from the service, navigate to the translations scripts directory and run the following command:

    cd scripts/translations
./download.sh

  3. Validate Translations:

    After downloading updated translations, go back to the root and validate them using the following command:

    cd ../..
yarn validate:locales

    It will validate the existence and correctness of certain locale files in locales/ folder.

  4. Make Changes:

    Edit translation strings in the /locales folder as needed.

  5. Validate Changes:

    After making changes, validate them again using the following command:

    yarn validate:locales

  6. Upload Strings:

    To export strings to the service, navigate to the /translations scripts directory and run the following command:

    ./upload.sh

  7. (optional) Validate builded platforms:

    After compiling filters into platforms, validate their locales by schema using the following command:

    yarn validate:platforms

    It will validate the JSON schema of filter rules for different platforms in a project.

Automatic Updates

The Update translations GitHub Actions workflow (.github/workflows/update-translations.yaml) runs download.sh weekly and on demand, validates the result with yarn validate:locales, and opens a pull request with the changes to locales/. Trigger it manually from the Actions tab. Uploading base English strings (upload.sh) stays a manual step.

The pull request is created with the default GITHUB_TOKEN, so it does not trigger the regular CI workflows; the update job itself runs yarn validate:locales, yarn lint, and yarn test, and reports failures via the Slack notification.