Skip to main content
Version: 2.x.x

Project configuration

Rather than specifying project details every single time you run a command, you can set them once and forget about it by creating a .tolgeerc file. You can still use command options explicitly, which will override the configuration.

Example configuration:

{
  "$schema": "https://docs.tolgee.io/cli-schema.json",
  "projectId": 123,
  "format": "JSON_TOLGEE",
  "patterns": ["./src/**/*.ts?(x)"],
  "push": {
    "files": [{
      "path": "./public/i18n/en.json",
      "language": "en"
    }],
    "forceMode": "OVERRIDE",
  },
  "pull": {
    "path": "./public/i18n"
  }
}
tip

We use cosmiconfig to parse the Tolgee configuration file, which means you aren't limited to naming it .tolgeerc. You can use any of the following:

  • .tolgeerc
  • .tolgeerc.[json|yaml|yml|js|cjs]
  • .config/tolgeerc
  • .config/tolgeerc.[json|yaml|yml|js|cjs]
  • tolgee.config.[js|cjs]
  • or include config from custom location with tolgee --config <location>

You can also store your config in package.json, under the tolgee key.

All the paths in the config are relative to the config file location.

List of properties​

projectId​

Integer or integer string (i.e. 4242 or "4242"). ID of the project on the Tolgee server. It is shown when you first add an API key, but you can also easily find it in the URL: app.tolgee.io/projects/{projectId}.

By default, Tolgee uses its own internal extractor which looks for use of the Tolgee SDK.

apiUrl​

String. URL to the Tolgee instance you're using. If you're using Tolgee Cloud, you can ignore this.

apiKey​

String. Api key to tolgee platform. It can be a Personal Access Token or a Project API Key.

Make sure you don't leak your API key

Use apiKey only if you are loading it from an environment or other secured source (supported in .js or .yml files) or your config is not public.

In most cases, it's better to use a one-time login command or set it via the TOLGEE_API_KEY environment variable.

format​

Format for push and pull operations. Check supported formats.

Options:

  • JSON_TOLGEE (default)
  • JSON_(ICU|JAVA|PHP|RUBY|C)
  • PO_(ICU|JAVA|PHP|RUBY|C)
  • APPLE_STRINGS
  • APPLE_XLIFF
  • PROPERTIES_ICU
  • PROPERTIES_JAVA
  • ANDROID_XML
  • FLUTTER_ARB
  • YAML_(ICU|JAVA|PHP|RUBY)
  • XLIFF_(ICU|JAVA|PHP|RUBY)

extractor​

String. Path to the custom extractor to use, relative to the .tolgeerc file.

patterns​

List<String>. File glob patterns to your source code, used for key extraction.

strictNamespace​

Boolean. Require namespaces to be reachable (at extraction), turn off if you don't use namespaces. (Default: true)

defaultNamespace​

String. Default namespace used in extraction if not specified otherwise.

parser​

Enum<react|vue|svelte>. Tolgee detects which parser to use automatically from the extensions of matched files, with this option you can override it.

Push options​

Related to push command, which imports the keys into the platform.

push.files​

List<{path: string, language: string, namespace?: string}>. Define, which files should be pushed and attach language/namespace to them. By default Tolgee pushes all files specified here, you can filter them by languages and namespaces properties. Path can be a glob, if you want to include multiple files.

push.languages​

List<String>. Specifies which languages should be pushed from push.files.

push.namespaces​

List<String>. Specifies which namespaces should be pushed from push.files.

push.forceMode​

Specifies how to solve potential conflicts in the pushed data.

Options:

  • OVERRIDE - update everything according to local files
  • KEEP - create only non-existent strings, don't touch existing ones
  • NO_FORCE - throw an error, if there are any conflict

push.overrideKeyDescriptions​

Boolean. Override existing key descriptions from local files (only relevant for some formats).

push.convertPlaceholdersToIcu​

Boolean. Convert placeholders in local files to ICU format. (Default: true)

push.tagNewKeys​

List<String>. Specify tags that will be added to newly created keys.

push.removeOtherKeys​

Boolean. Remove keys which are not present in the import.

Pull options​

Related to pull command, which exports the keys from the platform.

pull.path​

String. Path to a folder where the localization files are stored. (Structure itself can be defined with fileStructureTemplate)

pull.delimiter​

Single char, or null. Used as a structure delimiter.

By default, Tolgee interprets . in string keys as nested structures. You can use other delimiter, or disable this behavior by specifying null or empty string "".

pull.languages​

List<String>. List of languages to pull. Leave unspecified to export them all.

pull.namespaces​

List<String>. List of namespaces to pull. Defaults to all namespaces.

pull.states​

List<String>. List of translation states to include. Defaults all except untranslated.

pull.tags​

List<String>. List of tags which to include.

pull.excludeTags​

List<String>. List of tags which to exclude.

pull.supportArrays​

Boolean. Export keys with array syntax (e.g. item[0]) as arrays.

pull.fileStructureTemplate​

String. This is a template that defines the structure of the resulting .zip file content.

The template is a string that can contain the following placeholders: {namespace}, {languageTag}, {androidLanguageTag}, {snakeLanguageTag}, {extension}.

For example, when exporting to JSON with the template {namespace}/{languageTag}.{extension}, the English translations of the home namespace will be stored in home/en.json.

The {snakeLanguageTag} placeholder is the same as {languageTag} but in snake case. (e.g., en_US).

The Android specific {androidLanguageTag} placeholder is the same as {languageTag} but in Android format. (e.g., en-rUS)

pull.emptyDir​

Boolean. Empty path folder before inserting pulled files.

Sync options​

sync.backup​

String. Store translation files backup (only translation files, not states, comments, tags, etc.). If something goes wrong, the backup can be used to restore the project to its previous state.

sync.continueOnWarning​

Boolean. Continue the sync regardless of whether warnings are detected during string extraction. By default, as warnings may indicate an invalid extraction, the CLI will abort the sync.

sync.removeUnused​

Boolean. Delete unused keys from the Tolgee project.

Tag options​

tag.filterExtracted​

Boolean. Extract keys from code and filter by it.

tag.filterNotExtracted​

Boolean. Extract keys from code and filter them out.

tag.filterTag​

List<String>. Filter only keys with tag. Use * as a wildcard.

tag.filterNoTag​

List<String>. Filter only keys without tag. Use * as a wildcard.

tag.tag​

List<String>. Add tag to filtered keys.

tag.tagOther​

List<String>. Tag keys which are not filtered.

tag.untag​

List<String>. Remove tag from filtered keys. Use * as a wildcard.

tag.untagOther​

List<String>. Remove tag from keys which are not filtered. Use * as a wildcard.