Applanga Figma Plugin

A plugin for translating Figma files with Applanga.

Table of Contents

  1. Installation in Figma app
  2. Configuration of the Applanga Project & Plugin
  3. Usage
    1. Uploading content for translation
    2. Translate your Figma file
    3. Uploading translated screenshots
    4. Uploading translated screenshots for multiple languages
    5. Inspect & Edit Ids
    6. Placeholders Replacement
    7. Check & Align file
    8. Connection Settings
    9. Creating translation orders via the plugin

Installation in Figma app

  1. Go to your Figma file and open Menu > Plugins > Manage Plugins.
  1. Click Plugins in the left menu.
  2. Click Browse all plugins button.
  3. Enter "Applanga" in the search box and then click Install button next to the Applanga Localization Plugin plugin.

Configuration of the Applanga Project and Plugin

For a new project


  1. Create a new project in Applanga Dashboard.
  2. Follow the prompts and select the Figma integration option.
  3. Copy the Applanga API Token by clicking on the clipboard icon. You will not be able to upload content without it.
  4. Click on "Go to Project" to confirm the configuration (This will automatically whitelist all IPs so you are able to upload Figma content to the Applanga project using the plugin! If needed, you can remove ::/0 and 0.0.0.0/0 then add your specific IP address. This will allow only you to upload content.)

For an already existing project


  1. Go to Project Settings of the project.
  2. Add ::/0 and 0.0.0.0/0 or the authorized IP addresses in the List of IP's authorized for API upload. This will authorize you to upload Figma content to the Applanga project using the plugin!
  3. Copy the Applanga API Token by clicking on "Show API key" and then the clipboard icon. You will need it to start using the plugin.
  4. Scroll to the bottom of the Project Settings page and click "Update".

In the Applanga Plugin


  1. If the design file is not yet connected to an Applanga project, the plugin will open on the Connection Settings page
  2. Enter the Applanga Project API Token
  3. Confirm the Applanga Project Name is correct
  4. If your Project has Branching enabled, use Select Branch to configure the Branch that should be used by the plugin for uploads and downloads.
  5. If you want to create orders via the plugin, add your Personal Access Token
  6. Click Connect to Applanga project

Back to Top


Usage

 


Uploading content for translation

Default Upload Options

  • Project name: this is set to the Applanga project which the plugin is currently linked via the API token (not editable)
  • Branch name: for projects with Branching enabled, it shows the Branch that is configured for the plugin as upload target (not editable)
  • Select language: the source language is preselected by default, but you can select any language for upload. This is particularly useful for uploading localized screenshots for testing
  • Upload Scope:
    • All Content: All content from the design file is included in the scope of the upload
    • Only Current Page: Only content from the current page is included in the scope of the upload
    • Only Selected Content: Only the content from the selection is included in the scope of the upload
  • Include Text and Include Screenshots: select what you would like to upload to the Applanga project. By default both options are selected for source language, and only Screenshots option is selected for target language upload.

Advanced Upload Options

  • Upload new/missing text: with this option enabled, any text present in the file and not yet on Applanga is uploaded (by default enabled).
  • Merge new duplicated text into a single Applanga string: when this option is enabled during upload, for every text that is not on Applanga yet, all duplicates found in the file for that text are 'merged' into a single new Applanga Id. If this option is disabled, one string Id is created for each of the duplicate texts (by default enabled).
  • Set status: this option sets a status for all new content uploaded to an Applanga project. To update the status of an already existing string on Applanga, use the Change status option.
  • Merge Figma text with existing Applanga strings: when this option is enabled during upload, if a string with the exact same text already exists, the existing string Id is applied to the Figma file instead of generating a new one. If multiple such strings exist, one is chosen randomly (by default enabled).
  • Update existing Applanga strings with changes made in Figma file: when this option is selected, the corresponding strings on Applanga will be overwritten with the content from the Figma file (by default enabled).
  • Change status: this option changes the status of an already existing string on Applanga.
  • Apply Placeholder Conversion: if development placeholders exist in the Applanga project and they are mapped in the Plugin Placeholders Replacement options, this will convert placeholders on download to the Figma file.
  • Tag all strings in upload scope with: to link the strings in scope for the upload with a tag, enable this option and enter a tag name.
  • Ignore formatting in text: if there is formatting applied to the Figma text (like bolding, font size, font family, etc) the formatting will not be included in the upload to Applanga.
  • Remove leading & trailing whitespaces: this option will remove any leading or trailing spaces from your Figma strings when you upload them to Applanga.
  • Exclude untranslatable content: this option will exclude specific types of untranslatable content from upload to the Applanga project. Options for exclusion from upload include only numbers, times and dates, special characters, Lorem ipsum placeholder text, symbols, or single characters.
  • Include Screenshots without Linked Text: if selected, screenshots that couldn't be linked to any text are uploaded to the Applanga project (by default disabled).
  • Include Hidden Content: determines if the hidden (close/open eye icon) content is included in translation scope (by default disabled). Please note, that there may be invisible elements that will be included in scope, because they are invisible for other reasons than the “visible” property status.
  • Include Locked Content: determines if the locked (padlock icon) content is included in translation scope (by default disabled).

Important notes!

  • If you want to exclude pages from the upload, add 3 underscores in front of the element or page name (___).
  • The upload for large files (particularly screenshot uploads) may take several minutes.
  • You must whitelist your IPs in the Applanga Project Settings page before you can use the plugin! See the Configuration section for more details.

The Upload button is only active if there is an upload language selected and either the Text or Screenshots option is selected. The Activity log will display the progress indication and error messages.


Back to Top


Renaming String IDs

When new IDs are being created on Applanga as part of the upload, there is the option to manually edit any new IDs. The dialog will not display if only screenshots are being uploaded or there are no new strings to upload to the Applanga.

  • Click the source text, to expand it to display the full source content.
  • Click the suggested string ID to edit it.
  • Click Confirm to approve the edits. You can also unconfirm to restore the original ID value. If the Confirm button becomes red, the string ID is invalid. Most often its value conflicts (the same ID, but different source text) with an ID that already exists in Applanga or with a newly created ID. Hover over the button to see a more detailed error message.
  • Only Approved or All (default) determines if all of the strings are to be uploaded to Applanga or only confirmed strings (green checkbox). If any edits are made to the string IDs, only those approved will be included in the upload.

The Upload button starts the upload immediately. During the upload process, an activity log will inform you about the progress and any errors.


Back to Top


Translate your Figma file

Once translations for your content are available on Applanga, you can use the plugin to download the translations and populate them in your file.

You may prevent any part of your file from being translated by locking or hiding the elements out of scope and/or by limiting the download to specific pages (see Scope below).

Download Options

  • Project Name: is set to Applanga project with which the plugin is currently linked via the API token (not editable).
  • Branch Name: for Projects with Branching enabled, it shows the Branch that is configured for the plugin as download source (not editable).
  • Select Language: select the target language to be downloaded. Please note that the Download button will not be active until a target language is picked (none is selected by default).
  • Mode: determines if strings from target or draft translation values are populate (by default Target plus Draft will be populated).
  • Scope: determines if the whole file is processed or only the currently open page (by default all content is in scope).
  • Overwrite Hidden Content: determines if the hidden (close/open eye icon) content is included in scope (by default excluded).
  • Overwrite Locked Content: determines if the locked (padlock icon) content is included in scope (by default excluded).
  • Merge Figma text with existing Applanga strings: allows the linking of strings missing Applanga Ids to an existing string Id in the connected Applanga project. Please note, the text matching to the source text in Applanga project may not work or may give false positives if the file is (partially) translated.
  • Ignore leading & trailing whitespaces: this option will remove any leading or trailing spaces from your strings when you download them from Applanga into your Figma file.
  • Apply Placeholder Conversion: converts development placeholders as found in Applanga to the mapped text as set in the Plugin Placeholder Replacement options.
  • Ignore formatting in text: if you ignored formatting in text during upload, you will need to apply this setting to download translations. You will also need to manually re-apply any formatting once translations are downloaded.

Important notes!

  • Please be aware that translation download for very large files may take several minutes.
  • Note that any content that has 3 underscore characters (___) at the beginning of the element or page name is excluded from the scope.
  • The translation download will overwrite the source text in your file. It is recommended to create a copy of the file for the translation process. You can also revert back to your starting point by selecting your source language and downloading it again.
  • You will need all fonts used in your Figma file installed locally. Translations won’t be populated for text where fonts are missing. There is a Font Missing warning in the upper right corner in the Figma interface that gives you more info.

The Download button starts the download immediately. The button is only active if there is a download language selected. During the download process, an activity log will inform you about the progress and any errors.

If there are fonts missing or the string Ids are not aligned, the download of translations into Figma might fail. Use the Check/Fix Files option to get a list of all the missing fonts and to align the Applanga Ids in your file with the ones of the connected Applanga project. For more information on managing Missing Fonts, see Figma's documentation.


Back to Top


Uploading translated screenshots

If you want to upload screenshots of your translated Figma file back to Applanga, for example, if you want somebody to review the translation in-context, please follow these steps:

  1. Go to Download and select a language, run the download process.
  2. After the download is finished, go to Upload and select the language again but make sure that you only select Screenshots in the upload options

Back to Top


Uploading Translated Screenshots for multiple languages at once

This feature starts an automated process that will, step by step, download translations for a language, take screenshots of the translated Figma design, and upload the translated screenshots back to Applanga for all languages selected one after the other automatically.

In order to upload translated screenshots for multiple languages at once, in the plugin UI, choose the Batch Screenshot Upload option. In the subsection of the Batch option, you can select which languages to include (all or everything but source), which set of strings (Draft or Target), and which layers (all or only the currently selected one) will be in scope for the batch process.


Back to Top


Inspect and Edit Ids

Inspect & Edit Ids allows users to view the Applanga string Ids connected to specific text in the respective design file. Users can also create new strings Ids by removing the current Id and setting a new one via the plugin.

  1. Select the element of the design file to display string Ids in the plugin
  2. Click on the String Id text field to edit the string Id, then select the checkmark to approve for upload (if an Id already exists for a given text on Applanga, users can search and apply that specific Id)
  3. Once Ids are updated, click Upload

Important Notes!

  • Screenshots are not automatically uploaded with strings when using the Inspect & Edit Ids option. Users can manually assign strings on the Applanga dashboard using the screens tag. See the tags page for more info.

Back to Top


Placeholders Replacement

When transferring text from design files into app strings on Applanga, it is often necessary to add certain variables or placeholders to the text so it is usable in the app (e.g. replace numbers, counters, dates, time, etc with placeholders such as %d, %s, etc)

However, these variables in the text will appear in the design files which interferes with the ability to match the design to the app 1:1

The Placeholders Replacement option acts as a placeholder conversion. It allows plugin users to replace any variable found in the app's text with a predefined text element. For example, with a mapping of “%d” to “5”, the string “Lisa bought the %d apples” would appear as “Lisa bought the {5} apples” in the design file.

Replaced/Converted placeholders in the design file are written inside curly brackets {} to prevent any accidental edits to these text fields.

  1. Enter the placeholder text (e.g. %d) as found in the app strings to the Placeholder column in the plugin
  2. Enter the desired text (e.g. 5) the placeholder should be replaced with on download in the Replacement Text column
  3. Click the Checkmark to save this conversion and add more
  4. Click Save to save all mapped Placeholder Replacements

Back to Top


Check and Align File

Check/Fix File Options

  • Check Missing Fonts: this option lists all fonts used in the currently selected Figma file, but not present on your system (e.g. PC/Mac). Translations can only be downloaded for text where the font is available. For more information on managing Missing Fonts please see Figma's documentation.
  • Link Figma text with existing Applanga IDs: this option tries to match the text in the file with existing Applanga IDs. It's similar to Merge Figma text with existing Applanga strings in download options, but is not limited to selections.
  • Remove all linking to Applanga IDs: this option allows users to unlink Applanga string IDs from a previously uploaded Figma file. When users upload a previously Applanga-integrated file to a new project, the existing Applanga IDs can cause issues with the upload to the new project. This option prevents issues with both uploading and downloading content from Applanga.
  • Migrate IDs to new plugin version: Applanga plugin update from version 8 to 9 changed how string IDs are stored; this option will migrate this string Id storage method if you have previously uploaded the same Figma project with the Version 8 plugin. This migration will also happen automatically during the upload process.

Back to Top


Connection Settings

  • Applanga Project API Token: the API Token from your Applanga project settings should be added here.
  • Applanga Project Name: this displays the project name that corresponds to the entered API token (not editable).
  • Personal Access Token: the PAT from your account can be added here to enable creating translation orders via the plugin (optional).
  • Select Branch: if your Project has Branching enabled, select branch that should be used by the plugin.
  • Connect to Applanga project: saves the connection settings on your local machine. The selected options are saved separately for each Figma file and will be loaded next time you open the file on your machine and start the plugin.

Back to Top


Creating translation orders via the plugin

Figma users can create translation orders via the Applanga plugin for Figma. This option allows you to combine the upload of content to Applanga with creating a translation order.

Preconditions for ordering via the plugin

  • Before you can create translation orders via the Figma plugin, you must create a Personal Access Token (PAT). The PAT enables you to create orders using your Applanga account, without logging into the dashboard. See the Personal Access Token documentation for more information. Be sure to select the Orders persmissions when creating your PAT. Once you create your PAT, you will need to add it to the plugin's Connection Settings.
  • Only languages that are part of the project on Applanga are available for ordering. If more languages are required, those languages need to be added on the Applanga project dashboard first.

How to create an order

  1. Click Create Order
  2. Select the scope of the order, select the languages for the order, then click Continue
  3. Provide an Order Brief then click Continue (some projects will require you to complete custom order brief fields in addition to the general brief)
  4. Wait for the order to be submitted, then click Done
  5. The Translation Orders page will display all open orders in the Applanga project. Click the back arrow to navigate back to the plugin menu.
  6. Once an order is done, you can download the translations to the Figma file.

Back to Top