Skip to main content
Version: 2.x.x

Syncing strings

The code extractor is a feature of the CLI that allows you not to worry about manually finding strings and adding them to the localization project, and leave this up to the CLI. No more stories about keys that have been forgotten!

The CLI will look through your code project and look for usage of the Tolgee SDK, and give you all the keys used in your app. You'll then be able to push the missing keys to the platform, and delete keys that have gone unused to keep your localization project clean.

During analysis, the extractor will also look for magic comments which are basically explicit directives you can give to the extractor.

If you need to use custom logic to extract strings, we got you covered! You can use a custom extractor and have the CLI handle the rest for you.

info

All commands extracting keys from code require a global parameter --patterns <patterns...> or config.patterns.

Check for extraction warnings​

When extracting, the CLI might not be able to fully extract strings for a variety of reasons (e.g. dynamic data). When this happens, the CLI emits a warning and tells you the file and line where this warning was emitted.

tolgee extract check
info

When running this command on CI, the CLI automatically adds review annotation warnings directly in your commits and pull requests.

See an example here.

Duplicate key detection limitations​

Currently, the CLI does not detect when the same key appears multiple times in your code with different default values. For example, if you have:

<T keyName="save-btn" defaultValue="Save" />
<T keyName="save-btn" defaultValue="Save (Changed)" />

The CLI will not warn you about this conflict. This is a known limitation that may be addressed in future versions.

Workaround: Use consistent default values across your codebase, or rely on the Tolgee Platform as the single source of truth for translations rather than default values in code.

Default values and base language behavior​

When you first sync a key with a default value, the CLI will create the key in your Tolgee project and set the default value as the translation for your base language. However, subsequent changes to default values in your code will not automatically update the base language translation in Tolgee.

For example:

  1. You add <T keyName="welcome" defaultValue="Welcome" /> and run tolgee sync
  2. Tolgee creates the key "welcome" with "Welcome" as the English (base language) translation
  3. Later, you change the code to <T keyName="welcome" defaultValue="Welcome Back" />
  4. Running tolgee sync again will not update the English translation to "Welcome Back"

This is by design to prevent conflicts between code changes and translations managed in the Tolgee Platform.

Comparing projects​

You can think of this utility as a dry-run of tolgee sync. You can use it to see the added/removed strings and see if what it tells you seems right, or if it got something wrong.

tolgee compare

Synchronizing projects​

tolgee sync [options]

Options:

  • --backup <path> (short: -B) – Optional. Path where a backup should be downloaded before performing the sync. If something goes wrong, the backup can be used to restore the project to its previous state.
  • --remove-unused – Set this flag to also remove keys from the platform that are unused.
  • --continue-on-warning – Set this flag to continue the sync even if warnings are detected during string extraction. By default, as warnings may indicate an invalid extraction, the CLI will abort the sync.
  • --yes (short: -Y) – Skip prompts and automatically say yes to them. You will not be asked for confirmation before creating/deleting keys.

Dumping all strings​

This is more of a debug command, which you can use to troubleshoot extraction issues, use as a way to test your custom extractor, etc.

tolgee extract print