Files API

Integrations with Smartling are most effectively accomplished by using standard resource files. See the complete list of supported file types. Assuming that Smartling doesn't have a connector for your platform, the best practice for API integrations is to choose the "natural" resource file format for your platform or tech stack. 

For example, for Android applications (the Android XML resource files) and for iOS strings, the (.strings or .xliff file formats) are supported by those platforms.

For web applications, developers should use, if available, standard localization features that are built into the part of the stack that is being localized. For example, Java supports standard localization with Java property resource files. Alternatively, developers can choose a localization library that meets their needs. For example, localizing your React front-end with React INTL.

In the rare exception that no standard localized resource format is available, then we recommend choosing to serialize the content in JSON or XML, which are flexible and easily map to databases if your content happens to be stored in a custom database. CSV and Excel are never recommended because they are the least suited to localization and translation (even though they are commonly used for that purpose).


Upload Content

Here's a simple example of uploading your file to Smartling: 

curl -X POST -H "Authorization: Bearer {token}" -F "file=@file.properties;type=text/plain" -F "fileUri=file.properties" -F "fileType=javaProperties" 'https://api.smartling.com/files-api/v2/projects/{projectId}/file'

The above example will upload your Java properties file directly into the Smartling project identified by the {projectId}. Smartling will ingest this file, parse out the keys and texts as strings for translation. At this point, content is ready for translation.

There are several different options that can be used when uploading content into Smartling. 

Want to translate specific placeholders? See JSON - Default Placeholder Format.
Only want certain paths of your XML file translated? See Custom XML - Specifying Paths.
Are you using ICU Message Format? See ICU Message Format.

For a full spec on file upload, consult the Files API.

File Type

If you're just starting to work with Smartling, we recommend that you review the documentation for the file type that you plan to use in order to better understand how that file is handled, by default. Then, upload some example files and review them in the Smartling Dashboard to confirm that the strings were created as you expected. Some items to keep in mind:

  1. The correct number of strings were extracted.
  2. Placeholders were correctly recognized.
  3. Other metadata is reflected the way that you wanted (such as string instructions, keys, and special cases, such as plural strings).
  4. Try downloading the "pseudo translation" of the files to see what they might look like once they've gone through the translation process.

If the file doesn't capture and deliver the way that you thought it would, review the documentation for that file type to see which Smartling directives are available. These directives can change how your file is processed and the translated version is delivered. There are two ways to implement directives:

  • Directly in the file (inline) -OR-
  • As options (parameters) to your API call. 

The syntax of a directive to get a specific result might be slightly different when they are set as API parameters versus inline, inside of the file, due to requirements of escaping in the different contexts.

Download Content

Here's an example for downloading your translated file, using the Smartling Download File API.

curl -H "Authorization: Bearer {token}" "https://api.smartling.com/files-api/v2/projects/{projectId}/locales/{localeId}/file?fileUri={your-file-Uri}"

The above example will download your translated file for a locale of your choice. You can request your translated file at any time.

Typically, customers upload their file with a callbackUrl, and Smartling will make a call out to that callbackUrl when your file is 100% translated, or, they poll and check the file progress before downloading their file. Find out more about callbacks and of your file. 

Ready to use the Files API? Click here.

Was this article helpful?