Table of Content
XLSX, XLSM, XLTX, and XLTM are the spreadsheet file formats used by Microsoft Excel; they can also be read by and edited in other compatible programs such as LibreOffice and Google Docs.
File extensions: .xlsx, .xlsm, .xltx, .xltm
i18n type: XLSX
With these formats, all source strings and translations are in the same file, which differs from the usual source and language files structure in Transifex. When you upload a spreadsheet file that already has translations in it, Transifex will add both the source strings and translations to the database. Similarly, when you download the file from Transifex, translations from all languages will be in it.
Structuring your spreadsheet
Cell Formatting Any rows where the source string cell is not formatted as text (e.g. date/time) will be ignored and not imported. The purpose of this is to avoid breaking any formulas that may be used by the cell. |
Spreadsheets used for localization typically organize their languages and strings in columns. Each column represents one language, with the header row of the column specifying the language. And below that, you have the strings/translations for that language.
For example:
+=========+=========+
| English | French |
+---------+---------+
| Hello | Bonjour |
+=========+=========+
You can use either the languages' names or their ISO codes as values for the header/language row.
How Transifex finds the language row
Transifex is pretty forgiving about how you format your spreadsheet file. If you have rows above the languages row – for example, with instructions for your translators – Transifex will simply skip them.
So this file, for example, would still be compatible with Transifex:
+=========+===========+
| Use formal language |
+---------+-----------+
| English | French |
+---------+-----------+
| Hello | Bonjour |
+=========+===========+
And if your file has more than one sheet in it, and your strings aren’t in the first sheet, Transifex will still try to find them.
In general, Transifex will look for your strings this way:
Go through every sheet and row in the file in order.
Find the row which looks like the one with the language names.
Consider that row and the ones below it in the sheet that it was found in as the ones that hold the actual content.
Note: If multiple sheets contain localization content, then only the first sheet that meets the criteria will be parsed. The rest will be ignored.
Extra columns and duplicate phrases
Provide Context
By default, Transifex does not allow duplicate strings in Excel sheets unless you distinguish each phrase with a unique context. You can have columns between the language columns for context purposes. You can name such a column in any way you want, but a good convention is to name it Context.
Transifex won't treat it as a translatable string. The contents of the column are added as developer comments for the phrase and shown in the Editor to Translators. Each note can have up to 1,000 characters.
Below you can find an example where English is the source language and the Context column is present.
+=========+=========================+==========+
| English | Context | French |
+---------+-------------------------+----------+
| Hello | Appears in welcome page | Bonjour |
| Hello | Appears in signup page | Bonjour! |
| World | | Monde |
+=========+=========================+==========+
Warning Please make sure that the Context column is right after the column where the source strings are included |
Define keys in XLSX
In order to set the value of a key in an XLSX source file, you need to create a new column in your source file named "key". This "key" column should be next to (before or after) the source language column or next to (before or after) the "context" column.
The "key" column will get uploaded into the key field in Transifex. The key is useful for filtering in the visual context tool as well as for filtering in Transifex Web Editor.
Below you can find an example where English is the source language and "key" column is present.
Version #1:
+=========+=========================+==========+
| English | key | French |
+---------+-------------------------+----------+
| Hello | Appears in welcome page | Bonjour |
| Hello | Appears in signup page | Bonjour! |
| World | key1 | Monde |
+=========+=========================+==========+
Version #2:
+===========================+========+==========+
| key | English| French |
+---------------------------+--------+----------+
| Appears in welcome page | Hello | Bonjour |
| Appears in signup page | Hello | Bonjour! |
| key1 | World | Monde |
+===========================+========+==========+
Define the character limit in an XLSX source file
You can define character limits for the translations by adding this numerical limit in a separate column in your XLSX file.
Character limits must be added to a column named "Character limit". The name of this column is case insensitive and will consider spaces, dashes and underscores. As an example the following column names are acceptable:
character Limit
character-limit
chAraCtER_liMit
This column is not required, so in case you don't include this, Transifex will still parse your file.
Add tags to strings
You can add tags to strings directly in your XLSX file and then update your strings in Transifex via a simple upload using a dedicated column named "Tags".
The structure of your source file, in this case, will look like this:
+========================+=========================+==============+
| English | Tags | French |
+------------------------+-------------------------+--------------+
| Localization | homepage | localisation |
| The world of software | article, email | Bonjour! |
| Transifex | locked | Monde |
| Transifex app | notranslate | |
+========================+=========================+==============+
For any tag changes happening in Transifex (new tags are added, existing tags are removed) you can request the latest version of the XLSX content from Transifex and the updated tags will be exported as well.
Note This column is not required, so in case you don't include this in your XLSX file before uploading the file to Transifex, Transifex will still parse your content but no tags will be updated or exported once the file is requested. |
Get translation dates upon export
If you want to get the date of the latest translation applied to your strings whenever you request the XLSX file from Transifex, then all you need to do is to make sure that for every target language there is an extra column called "modified".
So, before you upload your XLSX source file to Transifex, make sure you follow the format below:
Example Format:
After your strings are translated in Transifex, when you request the file back, these columns will contain the date of the last translation applied to each one of the strings included in your file for every target language.
The following column names are acceptable:
modified
translation_date
modified_on
translated_on
Duplicate phrases
You can use the context column to differentiate between the same source phrases which should be translated in different ways. For example, if you have the word "Hello" twice in your file (the same key is used for both phrases), and you want to allow translators to translate it differently in each case, you should provide a different context for each one of the strings above to differentiate.
If you have duplicate English phrases and both "key" and "Context" are the same, Transifex will complain and will ask you to fix the error.
Note If both key and context values are present in the source file, then the key and context will participate in the hash generation process, otherwise (if key is missing) the source string + context will participate in the hash generation process instead. |
Mismatches between languages in the file and the project
In Transifex, each project has a set of target languages that it's translated to. If there are any differences between the languages in the uploaded file and the project, Transifex will try to deal with this as gracefully as possible.
Here's a look at a few possible scenarios:
If the file you upload has languages that aren't in the project, those languages will be ignored. Strings from those columns won't be added to Transifex nor appear in the Editor. To add those translations to Transifex, first, add the language to the project then re-upload the file. Any content that isn't added to Transifex will remain in the file, unchanged, when you download the file.
If the project has languages that aren't in the file, the upload will proceed without issues, though of course, no translations will be uploaded for those missing languages. You can still translate those languages in the Editor. And when you download the file, the extra languages will be added as new columns at the end of your spreadsheet.
If you are unhappy with the order the languages appear or with the style of the extra columns, you can edit the file offline to make it look as you want and upload it again as a source file.
Uploading/downloading options
If you upload a file through the Update Source File function in Transifex, all strings in the file will be extracted from the spreadsheet. This means both source strings and translations will be updated inside Transifex. If, however, you upload the file through the Upload File function, only strings from the selected language will be uploaded to Transifex. This gives you more control over which languages get updated.
When you download a file, however, all available translations from all languages will be included in the downloaded file. You can still choose to download only reviewed strings when downloading, in which case, only the reviewed translations will be used.