Translating with the Smartling Figma Plugin

The Smartling Figma plugin allows you to send Figma content to Smartling for translation within a job.

Using the plugin also provides automatic Visual Context for linguists in the CAT Tool. By default, the entire page’s visual context is submitted, but only images up to 50M pixels or 25MB are visible in the CAT Tool. If your source file contains large images, it’s recommended to reduce their resolution to avoid performance issues. For more details, refer to the Figma documentation.

Alternatively, you can submit images as frames to provide full visual context with no limitations.

You can monitor translation requests in both Figma and Smartling. Once translations are complete, you can apply them in Figma using the plugin.

This guide covers the steps to send content for translation and retrieve translations in Figma.

Important prerequisites 

1. Design changes made after submission will not be reflected in the translated file. 
   
   • For example, if you change a font after submitting a file, this change will not appear in the translated version of the file you will receive from Smartling. 
2. Ensure all components with translatable text are editable.
   • The plugin cannot apply translations to read-only components in Figma. See Figma documentation for more information on components. 
3. User permissions
   • The user sending content to Smartling must have edit permissions in Figma and must have access to Smartling as an Account Owner, Project Manager, or Requester. 

Step 1: Connect the Figma Plugin to Smartling

1. Follow the steps outlined here to connect the Figma Plugin to Smartling. 
   

Step 2: Prepare Figma content for translation

Although little to no file preparation is required before submitting Figma content for translation in Smartling, it may be helpful to review all text layers to ensure they are as expected.

• All text is ingested for translation by default. However, if you want to exclude specific words or strings from translation (placeholderize content), you can enclose them in curly brackets {} or {{}}, and then select the Placeholder checkbox when submitting the content for translation.
  • If you use curly brackets for another purpose and want the content inside them to be translated, be sure to replace them with another type of bracket before submitting the content.
• Text layer formatting affects string segmentation:
  • If a hard return (pressing “Enter”) is used within a text layer, Smartling will split the sentence into separate strings.
  • If you want text to appear as separate paragraphs but remain as one string, use soft returns (Shift + Enter) instead of hard returns.

Exclude content from translation

By default, all layers containing text are ingested for translation in Smartling. If your Figma file contains content you do not wish to translate, you can instruct the plugin to ignore it so it is not ingested for translation. To ignore/exclude specific content:

1. Click on the content you do not wish to translate in your Figma file to select it (e.g., a specific text node or element within a page).
2. From the plugins menu or actions menu, select Ignore Strings. 
   
   
3. The modal will display the selected content. Click the + (plus) button to mark the content as non-translatable.
   
4. The selected item will then appear under Already ignored nodes, where you can see other nodes on the page that have been marked as non-translatable. 
   
   
   
5. To undo the ignore action, click the X button to remove it from the list of ignored nodes. 
6. Click Save when finished. 

Important Notes:

• You can view ignored/excluded content at the page level, not the file level. If a Figma file contains multiple pages, you must select each page individually to view which nodes have been ignored.
• Ignored/excluded content information is saved in the file metadata so you do not need to ignore content with each new submission, the ignored/excluded content information is retained for all future submissions. 
• If multiple users are working on the same Figma file, ignored content will persist across all submissions of the file. Any updates to the ignored/excluded content made by one user will impact others working on the same file.

Edit string keys, add string instructions, and set character limits 

A key (variant) is a unique identifier for a string. It allows for quick lookup of a string in Smartling or in the JSON file. By default, Figma provides a unique identifier for each string, which can also be viewed in Smartling.

You have the option to edit the default key values. Keys can contain letters, numbers, underscores, and hyphens but cannot contain spaces. Note that key names must be unique for each string and cannot be repeated.

To edit string keys:

1. Click on the content in your Figma file that you wish to edit (e.g., a specific text node).
2. From the plugins menu or actions menu, select Key Editor. 
   
   
3. The modal will display the selected content. Click the pencil icon to edit the string’s key (variant) or optionally add a string instruction or a character limit.
   
4. You can use the search field to find a specific string by its variant name or text.
   
5. Click the reset button to revert to the original value. If the variant field is left empty, the default variant value will be used.
   
6. Click Save once finished. 

Important Notes:

• Any edits to string metadata will persist across all submissions of the file, so you do not need to re-edit string metadata for each new submission.
• If multiple users are working on the same Figma file, changes to string metadata will persist across all submissions. Any updates made by one user will affect others working on the same file.

Viewing string keys in Smartling

• In Smartling, you can find the key name under the File/URL column in the Strings View.

• Search for strings with a specific key using the Key/Variant field.
• The Key/Variant search box does not support spaces. If your key name contains spaces in Figma, it will not return a result when searching in Smartling. It’s best to use underscores (_) instead of spaces in key names.

The CAT Tool

Users working in the CAT Tool can view the string key under Additional Details in the top-right panel, next to Variant.

Note that edited key names are also visible in the source and translated JSON file that you can download from the files tab within the Job Details page in Smartling, however, the original key names (not the edited key names) are found in the exported JSON via the Smartling Plugin action Export (Manual).

Step 3: Submit Figma content for translation

1. Open the Figma desktop app or launch Figma in your browser 
2. Open a new or existing Figma prototype file.
   
   • This is the source file that the Smartling plugin will convert into a JSON file for translation
   • You must have the file open in Figma to take any action on it via the Smartling plugin
   • It is recommended to wait until all components have loaded successfully into the Figma file before proceeding with translation
   • If your source file contains images, it is recommended that they are of a reduced resolution size, as larger images can cause performance issues. For more information, read the Figma documentation
3. Click Plugins > Smartling > Submit Translation from the Figma menu. 
4. Select the page you want to submit for translation > Next
   
5. Complete the Submit Translation dialog:
   1. Choose to add the content to an existing job and choose the existing job from the dropdown, or choose to create a new job and name the new job
   2. Give the job a due date.
      • This defaults to one day in advance from the current day, but you can update this to sometime in the future or the same day.
   3. You can give the linguists additional details on how you want the job translated by providing a description
   4. Choose to pre-authorize the job, meaning once you complete these steps, the job will automatically authorize and proceed with the translation in the target language's default workflow.
      • If you choose not to select this checkbox, the job will sit in Awaiting Authorization in Smartling until a user Authorizes the job for translation. This option allows the user to decide the workflow in which the language should be translated in, as well as view a cost estimate before commencing translation.
   5. Select the target languages for the translation (required)
      
6. Click Submit to submit the content to Smartling for translation.
7. Once complete, the Translation Submitted dialog will appear with the job summary.
   • Click the hyperlinked job name to open the job in Smartling on your browser.
8. Close to continue working in Figma.

Re-uploading Content

When submitting individual frames of the same page that has been previously submitted to Smartling within Figma, the previous frame will be removed from its original job. This is due to the file/page being unique, and so this is treated as a file overwrite. This results in the previous content being removed.

Cancel Translation

If content has been submitted for translation and you need to cancel the request, you have two options: 

1. Cancel the job in Smartling 
2. From within Figma, click on Plugins > Smartling > Translation Status > Cancel Translation 

If you select Cancel Translation, all source files related to the Figma file will be removed from their job(s) in Smartling. Any strings that are In Progress at the time of cancellation will be unauthorized. Any saved translations will remain available in the Translation Memory.

How to retrieve translations from Smartling

Once your translations are complete in Smartling, you can send translations directly to Figma by Applying Translations via the Translation Status model. Alternatively, a Smartling user can download the translated files from Smartling and manually import them into Figma. 

Import translations from file

To import translated JSON files into Figma:

1. Click on Plugins > Smarting > Import (Manual) from the Figma Menu.
2. Select your translated JSON file from your directory.
3. Click Open to import or Cancel to exit menu.
   
   

Export content to file

You can export a JSON file of your Figma page. One Figma page can be exported at a time. If your design has multiple pages, you will need to export each page individually.

1. To export content, click on Plugins > Smarting > Export (Manual)
2. Select the Page you want to Export. You can select multiple Pages to download.
3. Select the strings you want to include in the exported file. Click the downward arrow on each string to expand to view sub-strings.
4. Click Export
5. A zip file will download to your local drive, containing a PNG and a JSON of each of your Figma pages