Usage Guide

The Figma plugin helps designers to cooperate seamlessly with developers and translators. With the plugin, designers can see how different translations will look in the project and adjust everything accordingly. It helps to see changes as they are made and add the keys and information for developers to ensure proper development.

Here is a step-by-step guide on how to use the Tolgee Figma Plugin to work with localization straight from your Figma projects.

Installing and Connecting the Plugin

After installing the plugin from the Figma plugin page, go back to your Figma project and do the following:

1. Access the plugin by clicking the Actions icon in the toolbar (shortcut CTRL + K or ⌘ + K), or click the Figma button in the top left corner, then select Plugins → Manage Plugins…
2. Find and open “Tolgee”
3. Insert your API key
4. Keep the Tolgee URL default if you are not self-hosting
5. Click “Validate” and then “Save”
6. Done!

A full guide can be found on the Setup docs page

Push: Adding New Strings and Translations

If you are working on a new project and would like to start localizing, you need to provide key names to each text that you want to translate with Tolgee. To add the keys, you should**:**

1. Choose the frame or just the text for which you want to add the keys
2. Name your key
3. Click Push to upload the changes to Tolgee
4. By default, the plugin will create (or update) screenshots to the keys - you can disable this by unchecking the checkbox.
5. Then, if everything is okay, click “Push to Togee” to add the new keys
6. Now you should be able to find the key on the Tolgee platform, together with the screenshot of the text in your base language

The plugin uses Figma frames to decide what a "screen" is, so if the screenshots are not properly created, check if you wrap each screen in a frame. If a string occurs in multiple frames, the top-level one is taken.

Pull: Working with existing translations and keys

If you are working on a Figma file that already has the keys added on Tolgee, you can select the whole frame or just the text string and click “Pull” in the Tolgee plugin window to update them.

Connecting Figma to Existing Translations on Toggle

In case you have the keys on Tolgee, but not yet on Figma, you can connect them in this way:

First, click on the “Link” icon.

Tolgee

Second, select a key from the list of keys that you want to connect the text to. You can edit the text in the Search field to find any key in Tolgee. After you connect an existing key to the text, the "link" icon will be darker (or lighter when using the Dark theme).

Tolgee

To remove a connection, click on the "link" icon again and click Remove connection

Tolgee

How to Switch Languages and Add New Translations from the Platform

In the previous steps, we managed to add the keys to existing strings in your base language (English in this example). Once the keys are translated, you can change the language and import the translation from Tolgee into Figma. To do so:

1. Open the Tolgee plugin in FIgma
2. Select a language on the main screen
3. Click Replace.

If there are some keys with missing translation in the selected language, they will be displayed on this screen.

Tolgee

If you want to update only some translations, select the keys and click Pull.

If you want to update new translations for all texts, click Pull all.

Tolgee

Creating and Updating Page Copies

Copies can be used to work with the translated versions of the project without constantly switching between them in the same file. With our plugin, you can create the following page copies:

• Copy with key names - this creates a copy with all texts replaced with the corresponding key names. Duplicate pages that contain key names are particularly useful for developers, as they provide clear guidance on which key names to use in the code.
• Copy with languages - this creates a copy for each selected language with texts replaced with their translation in given language.

1. To create a page copy, first click ”Create a copy”
2. Choose whether you would like to create a copy with key names or with translations:
3. After you click Create, the plugin will automatically create new page(s) according to what you selected.

To update a copy to reflect the latest changes in the translation:

1. Open the copy of the page
2. Open the Tolgee plugin
3. Click Pull all to update all translations when no texts are selected.

If you want to update only translations of some text, first select the text and then click Pull.

Locating translation on the page

If you want to locate a string on the page, click on the more button and then on the Move to string button, which will align your Figma view so that the text is in the center of your screen.

Tolgee