Skip to main content
Version: 3.x.x

Setup and Settings

Installation​

Install the plugin from the Figma Community by clicking Open in… or Open in Dev Mode.

You can find the Tolgee plugin in Figma by clicking the Actions icon in the toolbar (shortcut CTRL + K or ⌘ + K), choosing Plugins & widgets, then searching for Tolgee and clicking Run.

Alternatively, click the Figma button in the top left corner, then select Plugins → Manage Plugins… and search for Tolgee.

First Run​

The first time you open the plugin it walks you through three steps. They are named after the three settings tabs, so what you fill in here is exactly what you will find later under Settings.

  1. Project connects the plugin to Tolgee and picks your language
  2. Strings & Keys decides how keys get named and which texts are skipped
  3. Upload options decides what travels with your keys when you upload

You can move back and forth with Back and Next, and everything you set here can be changed later in Settings.

The three-step first run, which mirrors the three settings tabsThe three-step first run, which mirrors the three settings tabs

Project​

This tab connects the plugin to Tolgee and sets the language your designs are written in.

Connection​

Paste your key into Tolgee Project API key. If you do not have one yet, see how to generate an API key.

Leave Tolgee URL as it is unless you run a self-hosted instance, in which case enter the URL of your own instance.

Once the key is accepted, the plugin shows the name of the connected project. Click it to open that project on the Tolgee platform, which is handy when you want to check something without leaving Figma.

Tolgee
The Project step of the first run, with fields for the Tolgee URL and the project API key, and a Connect buttonThe Project step of the first run, with fields for the Tolgee URL and the project API key, and a Connect button

Language​

Current language is the language your Figma texts are currently written in. Set it to the same base language your project uses in Tolgee, because everything you upload is treated as a translation in this language.

tip

Changing this selector later downloads that language into the current page, covered in the Usage guide. You can also create a translated copy of the whole page instead, which leaves the original untouched, covered in Page copies.

Advanced​

Two settings appear here only when the matching feature is switched on in Tolgee itself. When one is off, the plugin says is disabled for this project instead of showing the field, so you always know whether it is missing or simply not available.

Default namespace is applied to keys you newly create. It does not touch keys that already exist: a connected key's namespace is set in Tolgee, so moving one means disconnecting the string first. See namespaces for what they are.

Branch sets which branch your uploads and downloads target, defaulting to the main branch. A branch selector also appears in the plugin header, so you can switch without opening settings.

Tolgee
The Project tab once connected, showing the project name with a Disconnect button, the current language, and an Advanced section holding the default namespace and the branchThe Project tab once connected, showing the project name with a Disconnect button, the current language, and an Advanced section holding the default namespace and the branch

Strings and Keys​

Key Name​

Naming keys by hand is slow, and a team doing it by hand ends up with three different conventions in the same project. Turn on Prefill key name and the plugin proposes a name for every new string, built from where that text sits in your design.

Key format is the template. You build it from variables, your own text, and separators such as . or :. Click the field to pick from the available variables.

VariableWhat it inserts
{elementName}Name of the text layer
{elementText}The text itself
{group}Name of the nearest group
{component}Name of the nearest component
{instance}Name of the nearest component instance
{frame}Name of the nearest frame
{artboard}Name of the artboard frame
{section}Name of the nearest section

A format like {artboard}.{elementName} turns a layer called Submit inside a Checkout artboard into checkout.submit.

Not every text has every variable. A layer that sits outside any component has nothing to put in {component}, and in that case the plugin drops the variable together with the separator next to it, so you never end up with a stray dot in the middle of a key.

Formatting style keeps the casing consistent no matter how the layers were named. It is applied to the variables automatically.

  • keep original format
  • snake_case (element_name)
  • Snake_case (Element_name)
  • camelCase (elementName)
  • PascalCase (ElementName)
  • noSpaces (elementname)

A preview at the bottom shows the result as you build the format, so you can see the shape of your keys before committing to it.

tip

A generated name is only ever a starting point. You can edit any key by hand, generate names for part of a screen and fill in the rest yourself, or change them later with bulk operations.

Tolgee
The Strings and Keys tab with Prefill key name turned on, a key format being assembled from variables offered in a dropdown, a formatting style of snake_case, and a preview of the resulting keyThe Strings and Keys tab with Prefill key name turned on, a key format being assembled from variables offered in a dropdown, a formatting style of snake_case, and a preview of the resulting key

Ignore Strings​

Not every text layer is a translatable string. Prices, spacing labels, placeholder numbers and scratch notes all clutter the list and slow you down. These settings keep them out of the plugin so what you see is what you actually want to translate.

  • Numbers skips strings made only of digits, such as 100 or 42. Turn on Including formatted numbers to also skip values like 1,234.00
  • Hidden layers skips layers whose visibility is turned off in Figma. By default only the hidden layer itself is ignored, so turn on Including all child texts to skip everything inside a hidden frame too
  • Text layers with prefix skips layers whose name starts with the prefix you set in Ignore prefix. It is prefilled with an underscore, and you can change it to anything. This lets you mark scratch content in the layer list itself

Ignored texts stay in your design exactly as they are. They simply stop appearing in the plugin.

Tolgee
The Ignore Strings settings, with numbers, hidden layers and prefixed text layers all ticked, each with its extra option, and an underscore set as the prefixThe Ignore Strings settings, with numbers, hidden layers and prefixed text layers all ticked, each with its extra option, and an underscore set as the prefix

Upload Options​

This tab decides what travels alongside your keys when you upload them to Tolgee.

Update screenshots is on by default. Screenshots are what let a translator see where a string actually appears, which is often the difference between a correct translation and a plausible one.

Add tags attaches tags to every key you upload. Choose from existing tags or type a new one and press Enter. Tagging everything that comes from Figma is a common way to find design-originated keys on the platform later.

info

Tags travel one way only. A tag someone adds on the Tolgee platform does not appear back here.

Tolgee
The Upload options tab, with update screenshots and add tags both ticked, and the tag field offering the tags the project already hasThe Upload options tab, with update screenshots and add tags both ticked, and the tag field offering the tags the project already has

Setting Up a Page​

Settings apply to the whole file, but each page also needs to declare which language its text is written in. The first time you open the plugin on a new page, it asks with a short Set up this page screen.

Pick the language and click Confirm. You can change it later from the plugin header.

What Next​

With the plugin connected, the Usage guide covers the everyday work of connecting texts to keys, uploading them, and bringing translations back into your designs.