All Collections
For Developers
File Formats
Introduction to File Formats
Introduction to File Formats

An overview of how different file formats are handled in Transifex.

Transifex avatar
Written by Transifex
Updated over a week ago

Transifex supports over 46 localization file formats. You can learn more about each by clicking on their respective link in this section.

📝 Note: Are you using a file format unsupported in Transifex? Don't hesitate to contact us! We are constantly working on expanding our support for more file formats.


Encoding

For most file formats, Transifex uses UTF-8 encoding. This means files you upload to Transifex must be encoded in UTF-8, and all files downloaded from Transifex will be in UTF-8. There are some exceptions in cases where a file format specification requires a different encoding. For example, JAVA .properties files use ISO-8859-1, and Apple's .strings files can use either UTF-8 or UTF-16.

📝Convert Encoding: You might sometimes find issues with your file encoding. If so, please refer to this article for more information on converting it to the appropriate encoding.


Download Modes

Depending on your needs, you can download a different version for every file you have. These different versions are called modes. They come in handy in several different situations. For example, a developer may want only to use reviewed translations. Or, a translator may wish to translate a file offline using their desktop tool.

These are the available modes when using the Client or the API:

  • Reviewed: the file will include reviewed strings in the target language. All other strings will either be empty or in the source language (depending on the file format).

  • Proofread: the file will include all proofread strings in the target language. All other strings are either removed or returned with translations in the source language or empty (depending on the file format).

  • Translator: the file will be suitable for offline translation of the resource.

Some file formats will take untranslated entries and fill them in with source strings. So, if you use one of the modes mentioned above, you'll get a file where the untranslated strings won't be empty. There are several modes that you can use to bypass this rule. They're available when using the API.

  • Onlytranslated: the response will include the translated strings, and the untranslated ones will be removed.

  • Onlyreviewed: the response will include the reviewed strings. All other strings are either removed or returned with translations in the source language or empty (depending on the file format).

  • Onlyproofread: the response will include the proofread strings. All other strings are either removed or returned with translations in the source language or empty (depending on the file format).

These two modes above only apply to the following file formats: Apple strings, Chrome I18N, HTML, Java Properties, Joomla (.ini), JSON Key-Value, Microsoft Word (alpha), Mozilla properties, Plain Text (txt), RequireJS format, and Windows JSON (.resjson), GETTEXT (PO).

  • Sourceastranslation: the response will include the translated strings, and the untranslated ones will be filled with the corresponding source strings.

This mode is only supported for the following formats: Android, KEYVALUEJSON, PO, Properties (Java Properties), QT, SRT, Stringsdict, and YML.

For all other file formats, use the translator mode to get a file that leaves the untranslated entries empty. For some formats, such as Java .properties, the downloaded file will have the source string in the comment so the translator can translate the file faster.

Getting the file

When using the command-line client, you can specify the mode of the file you want to download with the --mode option of the tx pull command.

In the web interface, choose Download for use, Download only reviewed translations, or Download for translation.


Plurals

Transifex supports plurals for all file formats that support them, e.g., Android, Apple strings, Apple stringsdict, Gettext, Java, JSON with ICU plurals, Structured JSON, XLIFF, and YAML.

You can read more about plurals here.


Metadata and file formats

Below is the metadata (developer notes, character limits, tags, context, and occurrence) supported per file format. The table does not include file formats that do not support any form of metadata.

File-Format-Metadata2.jpg#asset:9504


The storage engine

Every project in Transifex has a set of resources. Each resource corresponds to a source file. If, for example, you have a project with two files for translation, foo.pot and bar.pot, you will need to create two different resources (e.g., foo and bar) and map each to the corresponding translation file.

Every project in Transifex is associated with a source language, which is the source language of your files.

Transifex will extract the source strings using a parser suitable for your i18n format and store them as translations of the source language when you upload the source file. Then, you can translate these strings into even more languages (target languages) by using the web editor or by uploading a file.

When importing a source file into Transifex, it will be saved and used as a template for all automatically generated translation files when the user wants to download them. However, some parsers do not guarantee that the downloaded translation files will be the same as the source file concerning any metadata present.

The engine in detail

Three internal structures in Transifex are of interest: Source Entities, Translations, and Template files.

Each resource inherits the project's source language, which can be other than English. However, we will use English as the source language in the following examples.

Source Entities

At the core of the Transifex translation storage engine are Source Entities. These are representations of actual translatable objects and their metadata, like comments.

For gettext PO files, a source entity corresponds to a msgid entry with all the metadata it carries (context, occurrences, comments, etc.).

Translations

Each entity has Translations to several languages — including the source language. A 1-1 relationship exists between an entity and a translation in a particular language. So, if you upload a fresh POT file with one msgid inside, you will end up with one source entity and one translation for English.

Template files

Transifex internally will remove the source strings and replace them with a hash when you upload a source file. Transifex will use that hash to insert the correct translations for the requested language when downloading the file. In essence, you're downloading the English file with the English content of it replaced with French content.


Importing a source file

Here are the steps taken when you create a new resource by uploading a new source language file:

  1. We identify the translatable entities/segments in the file.

  2. For each one, we create a new source entity in Transifex if one does not exist.

  3. Most source files include the string in the source language (in the case of Gettext POT, this is the msgid content). We store this string in the database as the source language translation if needed.

  4. We replace this string with a hash to mark the place of the source entity and replace it with the correct translation when exporting the translation file. The above architecture means that all translated versions of the file preserve the comments and non-translatable parts of the file.


Importing a target language file

When you upload a file, e.g., a French translation file, Transifex goes through all translations, locates the respective Source Entity, and updates its translation. Then, the file is deleted. This means that any content that may not be supported by Transifex (such as arbitrary comments in random locations in the file) might not be preserved.


Exporting a file

Transifex will take the template file and substitute all hashes with the French translations when you request to download the file in a specific language. Transifex can export different files based on the mode you specify.


💡Tip

Looking for more help? Get support from our Transifex Community Forum!

Find answers or post to get help from Transifex Support and our Community.

Did this answer your question?