Importing Translated Resource Files
There are two ways to import translations in Smartling - TMX upload of an existing Translation Memory, and importing a translated resource file of translations completed outside of Smartling that want to add to your Smartling Translation Memory.
This article covers the latter - importing a translated resource file.
Permitted Users and Supported File Types
Account Owner and Project Manager users can import translations for the following file types via the Files page:
* CSV files do not generate keys automatically and directives are required.
HTML processing and file imports are not compatible.
If your translations are in a Microsoft Office Document, the translations must be aligned to the source content. You can copy and paste the content to an Excel file and convert that into a CSV to proceed with file prep by making up a key for each string. Ensure each string has its own cell, in the same column.
This translation import is referred to as key-based import as it is based on a 1:1 mapping of an original language resource file and its translated version, using keys. A key is a unique identifier for a string. Most of the supported file types listed above are fixed file formats that generate keys for each string automatically. Unlike most, CSV files require manual creation of keys for each string. A key can contain letters, numbers, and some special characters (such as hyphens or underscores).
The import file must contain a unique key for each string, for example;
|Key||Source Strings||Translated Strings|
As the source language is required for this translation import, the translations are aligned at a string-level, meaning the source language maps to the target language per string, as seen above. Ensure your translated file is parsed correctly before importing to ensure the translations are truly aligned.
For CSV imports, it is important to align keys and strings per column, as shown above. Your file should have a column for keys, a column for the source language, and if you are importing source and translations in one file, a column for each translated language. Alignment on a row-level is not supported.
File directives are used to define the location of specific data in a file. CSV requires the use of directives with any upload to Smartling. Other supported file types listed above do not necessary require directives, depending on how you want to import the translation. If you want to simply upload a separate file for each language, including the source, directives are not required (excluding CSV). Importing one file with multiple languages will require the addition of file directives to ensure that Smartling can read where the keys are located in the file, and where the content you are importing is located in the file.
If you want to import a CSV of source content with translations, such as the following;
the directives you should use include:
# smartling.source_key_paths = 1
# smartling.paths = 2
In the example above, the first row is the header, so a header directive is required. 1 is the column number listing the keys, and 2 is the column number listing the strings you are importing. If the content includes placeholders, a placeholder directive would be required.
For this scenario, you would first upload the file with a path directive pointing to the source content. Once that has been uploaded, you should update the path directive to point to the French translations you are about to import, i.e., # smartling.paths = 3
Then in Smartling, proceed importing translations from step 4 outlined below.
As seen in the above example, you can upload a file that contains both source content and translated content. The file can also include multiple language translations. If your chosen file type requires the use of directives, simply use a file directive to point to the source path first, then change the path on the file to point to the respective target language for each re-upload.
If translated files are independent of the source file, each file can be uploaded individually.
In any case, just ensure to import a file in the source language first, and that each file contains the same keys for each string.
If the resource file contains source content in multiple columns, you can direct Smartling to upload source content from mulple columns by using [column number / locale code], after the directive. For example; # smartling.paths=2/en-US,4/en-US
However, you cannot direct Smartling to import translations from multiple columns. Translations must be imported from each column individually.
File Preparation Checklist
- The first step in importing translations is to ensure that the content in the source file is parsed correctly. This article gives details on how each file type is parsed.
- Use keys to identify each string and map the source string to the correct translation.
- Ensure the translations are in fact translations. Check that your translated file does not contain a different language, such as the source language if a translation for a string is missing. If the translated file does not have a translation for every source string, you should omit it for the purpose of importing to Smartling. Depending on your file format you may include the key but leave it blank/“empty”/null/“” or omit the key/value entirely.
- Use source file type directives to ensure that the file is parsed correctly so that Smartling ingests the file accordingly. Click on your chosen source file listed above to learn about directives.
The translations are saved to the Translation Memory as soon as the upload has been completed, regardless of the workflow step chosen.
If you happen to accidentally import translations for the wrong language (i.e., the directive in the file points to a different target language than the one you just imported the file to), it is imperative that you go to the Translation Memory that the project is writing to, find the strings that were imported inaccurately, and delete the terms before proceeding to reimport.
- Go to the project writing to the Translation Memory you want the translations from this import to be added to.
- Click the Files tab
- Upload the file in the source language first. If the source language is in the same file as the translations, use directives to point to the source (as outlined in the example above).
- Once the source content is upload, enter the file by clicking the tile. The target languages of the project will be listed under the source language.
- On the target language, you want to import translations to, click the ellipsis button beside the Download button
- Select Import Translations
- Upload the translated file. If the translations are in the same file as the source, use directives to point to the correct target and click save before uploading (as outlined in the example above).
- Choose the workflow step at which you want the translations: First Revision Step or Published. If you want the imported translations to be reviewed and approved by reviewers on your Smartling account before being published, choose the First Revision Step. If you're confident that the translation is of good quality, click Published. In either case, the translations are immediately saved to the Translation Memory as soon as the import is complete (step 11). The content is imported into the language’s default workflow. If your default language workflow has no post-translation steps, you should choose Published.
- To overwrite existing translations in Smartling with the translation import, select the Overwrite existing translations checkbox.
- Click Import
- A success message will display the total number of matched strings and list any import errors. An issue will be automatically created for each string with an import error.
- Click Start another upload to upload more translations in the same language. Click Close to close the dialog and commence importing translations for another language by repeating from step 5.
If there is an error message, it may be the result of one or more of the following:
- Placeholder mismatch
- Inconsistent file directives
- Different key/value pairs
The most common import error is placeholder mismatch. This may be caused by having different placeholder directives in the original and translated files. If a later import has no errors, these issues will be resolved automatically.
Another possible cause of a placeholder mismatch error is if the number of placeholders in the source is different from the number of placeholders in the target. If this error is flagged, the strings will still be imported but they will automatically be the first step in the language workflow, regardless if you chose published on step 8 above.
To rectify this:
- Ensure the number of placeholders in the source equal the number of placeholder in the target
- Ensure the placeholders are formatted correctly
- Ensure the placeholder directives are correct
Once these errors are resolved, you can re-import the translated file using the steps above.
Assuming that each source string has a translation, the total number of strings, matched strings, and imported strings should be equal. If the number of matched strings is 0, this could mean there is a misalignment of keys, or the file directives are not pointing to the correct translations. If translations are not matched, then they are not imported.
To rectify this:
- Ensure to check the strings keys and file directives before uploading
- Ensure each string has a unique key
- Ensure the keys are aligned to the translations
HTML processing and file imports are not compatible. Directing Smartling to HTML process the strings in a file can break the string into smaller components, and therefore they cannot be assigned a key, and a translation cannot be imported.
If you have a key-based resource file with previously translated strings that you would also like to have HTML processed, you must first upload the file without HTML processing, import the translations, then re-upload the source file with HTML processing turned on. Smartling will create new and different strings, and may be able to use SmartMatch to apply translations to them, but some strings may need to be completely re-translated within Smartling.
HTML processing of strings is recommended only if your individual strings contain large blocks of content that are formatted with HTML that are not well translated as individual strings. Contact Smartling if you are not sure the best way to handle your resource files.
Importing content is also available via API.