Config: Mapping Files
The tx config
command allows you to update the .tx/config
file that was created when you ran the tx init
command. This configuration file is used to map files in a local repo/directory to resources in Transifex. There are different options for mapping files that are already on your local machine (mapping
and mapping-remote
) or files that are remote on Transifex (mapping-remote
).
Before v0.13.0 of the client, the tx config
command was tx set
. You can still use tx set
; however, it’ll be deprecated in a future release of the client.
Running tx config interactively
If you run tx config
without any parameters, the client will guide you through an interactive configuration experience to configure the .tx/config
file.
Here’s a sample run of tx config
with the interactive experience:
Running tx config command for you...
The Transifex Client syncs files between your local directory and Transifex.
The mapping configuration between the two is stored in a file called .tx/config
in your current directory. For more information, visit
https://docs.transifex.com/client/set/.
Enter the path to your local source file: video.srt
Next, we’ll need a path expression pointing to the location of the
translation files (whether they exist yet or not) associated with
the source file ‘video.srt’. You should include <lang> as a
wildcard for the language code.
Enter a path expression: translations/<lang>/video.srt
Here’s a list of the supported file formats. For more information,
check our docs at https://docs.transifex.com/formats/.
1. SubRip subtitles - .srt
Select the file format type [1]: 1
You’ll now choose a project in a Transifex organization to sync with your
local files. You belong to these organizations in Transifex:
1. Dunder Mifflin
2. Bluth Company
Select the organization to use [1-2]: 1
We found these projects in your organization.
1. Emails
2. iOS
3. Marketing Videos
4. Website
5. Zendesk
6. Create new project (show instructions)...
Select the project to use [1-6]: 3
Updating source for resource marketing-videos.video-srt ( en -> video.srt ).
Setting source file for resource marketing-videos.video-srt ( en -> video.srt ).
Updating file expression for resource marketing-videos.video-srt ( translations/<lang>/video.srt ).
Here’s the content of the .tx/config file that was created:
[marketing-videos.video-srt]
source_file = video.srt
file_filter = translations/<lang>/video.srt
source_lang = en
type = SRT
Configuring one local file (mapping)
Setting up your .tx/config
file using the mapping
subcommand is the most common workflow. You should use this subcommand if you already have source/target language files on your local machine and you want to associate them with resources in Transifex. If you want to create mappings for multiple source files at once, consider using the mapping-bulk
subcommand instead (next section).
$ tx config mapping -r <project_slug.resource_slug> --source-lang <lang_code> \
--type <i18n_type> [--source-file <file>] --expression '<path_expression>'
Note
Before v0.13.0 of the client, the mapping
subcommand was an option: --auto-local
.
Here’s what each argument in the command means:
-r
or--resource
: Your project and resource slugs, separated by a dot. These slugs are found in your project's URL; together, they uniquely identify your translatable resources. For example, if you have a URL such aswww.transifex.com/myorganization/myproject/myresource/
, the resource identifier will bemyproject.myresource.
-s
or--source-lang
: This is the source language of your project, such asen
for English. This is the language you selected when you created your project.-t
or--type
: This sets the type of the resources in your project, e.g. to PO. See the File formats section for details about the i18n type of each format available.--expression
: An expression which reflects the file/directory structure of your translation files. The expression must be in quotes and contain the<lang>
keyword, denoting where the file paths differentiate per language, e.g.locale/<lang>/ui.po
.-f
or--source-file
: If your source file doesn't follow the naming schema specified in theexpression
argument, you can specify a custom path for the source file using this option. For example,locale/ui.pot
.
By default, when you run tx config mapping
, the client does a dry run of the command. To actually write the changes to the .tx/config
file, include --execute
in your command.
Example
Let’s say you have the following directory structure:
└── locale
├── ui.pot
├── fr_CA
│ └── ui.po
└── pt_BR
└── ui.po
Here's a sample tx config mapping
run:
$ tx config mapping -r myproject.myresource --source-lang en --type PO \
--source-file locale/ui.pot --expression 'locale/<lang>/ui.po'
Note
Your source file name doesn’t have to match your resource name, but keeping them consistent might help others who come along later.
You can run tx config mapping --help
to learn about additional options that are available.
Configuring multiple local files (mapping-bulk)
The mapping-bulk
subcommand can be used for mapping multiple local source files at once.
$ tx config mapping-bulk -p myproject --source-language en --type MD -f '.md' \
--source-file-dir locale --expression '<path_expression>'
Here’s what each argument in the command means:
-p
or--project
: Your project slug. This slug is found in your project's URL and uniquely identifies your project. For example, if you have a URL such aswww.transifex.com/myorganization/myproject/
, the slug will bemyproject.
-s
or--source-lang
: This is the source language of your project, such asen
for English. This is the language you selected when you created your project.-t
or--type
: This sets the type of the resources in your project, e.g. to PO. See the File formats section for details about the i18n type of each format available.-f
or--file-extension
: File extension of the source files to be mapped.--source-file-dir
: Directory where the source files with the specified file extension are.-i
or--ignore-dir
: Directories to ignore while looking for source files. This can be called multiple times, e.g.-i es -i fr
.--expression
: A path expression defining where translation files should be saved. The default value islocale/<lang>/{filepath}/{filename}{extension}
.
By default, when you run tx config mapping-bulk
, the client does a dry run of the command. To actually write the changes to the .tx/config
file, include --execute
in your command.
Example
Let’s say you have the following directory structure:
└── locale
├── pt_PT
│ └── intro
│ ├── get-started.md
│ └── index.md
├── intro
│ ├── get-started.md
│ └── index.md
└── index.md
To run tx config
for all the Markdown source files inside locale/
:
$ tx config mapping-bulk -p myproject --source-language en --type MD -f '.md' \
-d locale -i pt_PT --expression 'locale/<lang>/{filepath}/{filename}{extension}'
Configuring files from Transifex (mapping-remote)
If you already have a project in Transifex with resources that were previously uploaded — via the web UI for example — you can use the tx config mapping-remote
command to quickly configure the client. This is useful when you want to pull files from Transifex using the client, make changes to the files, and push them back.
$ tx config mapping-remote <transifex_url>
Note
Before v0.13.0 of the client, the mapping-remote
subcommand was an option: --auto-remote
.
You can either configure all the files in a project:
$ tx config mapping-remote https://www.transifex.com/<organization_slug>/<project_slug>/
Or a specific resource within a project:
$ tx config mapping-remote https://www.transifex.com/<organization_slug>/<project_slug>/<resource_slug>/
Running tx config mapping-remote
overwrites your existing .tx/config file.
The following options will be deprecated in a future release of the client.
There are a number of additional options available for the tx config
command.
Mapping the source file and source language for a resource
If you want to associate a source file with a specific resource in Transifex and set its source language, use the following command:
$ tx config --source -r <project_slug.resource_slug> -l <lang> <file>
You can use this for initializing a new mapping or updating an existing mapping.
Set individual translation files mapped to a language
The following command can be used to set individual translation files mapped to a certain language. This is useful when your translation files don't use a common naming schema and the mapping
subcommand cannot be used.
$ tx config -r <project_slug.resource_slug> -l <lang> <file>
Setting or changing the resource type
Using the -t
or --type
option, you can set or change the i18n type of a resource:
$ tx config -t <type> -r <project_slug.resource_slug>
To set or change the i18n type for all resources in a project:
$ tx config -t <type>
Setting a completion threshold to download files
You may want to download translations only for resources that have reached a certain translation threshold. For example, you only want to download when a resource is 80% translated or higher. To do this, use the minimum-perc
option to specify the minimum translation percentage required in order to download. You can use this option on a project or resource level.
As an example, this command sets the minimum translation percentage at 80% completion:
$ tx config --minimum-perc=80
Similarly, it has a mode option to define the mode for the downloaded files.