Transifex

Transifex

  • Documentation
  • CLI Client in Python (Deprecated)
  • Config: Mapping Files

Config: Mapping Files

We released a stable version of a new Transifex Client, compatible with the API 3.0, and offered as single executable.

Please start using the new Transifex CLI here, since this software is considered deprecated (as of January 2022) and will sunset on Nov 30, 2022.

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 as www.transifex.com/myorganization/myproject/myresource/, the resource identifier will be myproject.myresource.
  • -s or --source-lang: This is the source language of your project, such as en 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 the expression 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 as www.transifex.com/myorganization/myproject/, the slug will be myproject.
  • -s or --source-lang: This is the source language of your project, such as en 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 is locale/<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.

Additional tx config options

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.

CONTINUE READING