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://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.

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.

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.