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"
}
}
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 filesKEEP
- create only non-existent strings, don't touch existing onesNO_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.