📚 Figma plugin series
This article is part of the Figma plugin localization workflow series that outline proven integration approaches of the Figma plugin in the product's design and development stages. The series consists of
Before diving in, check out our documentation describing the installation and configuration of the Figma plugin, as we will skip this step. Also, take a look at the rest of the Figma-related articles to find more helpful examples and guides.
🎈 The Use Case
Using Figma as the source of truth for adding new and modifying existing source keys has both stark advantages and disadvantages. The main disadvantage is that controlling all the content from Figma can slow down other teams since they either need to make the change from Figma or have somebody else do it. On the other hand, the great benefit of this approach is that the designs wholly reflect what the product actually looks like. This is amazing, especially when the designers iterate over existing designs, as they have the guarantee that they're designing the exact content the users interact with. When the content between Figma and Localazy is detached, the first step for designers when iterating existing designs is to check their own product in production and how much it's changed since the latest design phase.
Such a tight connection between Figma and the localization resources is common for teams operating under the agile workflow and have separate groups of people responsible for the design, translations, development, and management. Once finished, the designers ping the localization/content manager (or product manager), who modifies the textual content within the designs and optionally changes the node IDs to be more readable for others further in the development flow. Once validated and uploaded, the translators and developers can take over and use the created source keys.
There are still a couple of open questions which should be answered before fully committing to this workflow - such as file naming within Localazy so that the developers understand which keys to use. Let's go through all of it together.
If you feel like such a tight connection between Localazy and Figma is not for you or would like to use the Figma plugin merely as a tool to preview the designs in other languages, check out the Preview design in other languages (todo: link) article.
Why restrict ourselves to a Single Source of Truth?
You may ask why we should restrict ourselves to uploading content only via Figma. Based on our experience, allowing yourself to upload content to the same Localazy project from multiple sources will lead to overwriting your content sooner or later. In better cases, you would change the source keys uploaded from a different source to the latest values you actually want to use. In the worst case, you'd create a new key and upload it to an existing file in Localazy without knowing such a key already exists. By doing this, you would not only change the source value but also put the existing translations into Source changed state, and it may happen that the translators would update the translations before you realize the mistake. To undo all the translations later would be time-consuming and, in the case of paid translations, also quite costly.
People can still make mistakes. It's just less likely and easier to remedy. The safest way to prevent this is to always restrict yourself to a Single Source of Truth.
🔌 Connecting to Localazy
First of all, set up a new account in Localazy. Create a new project that will be connected to our product (via the CLI, API, or other means).
We will add new keys and modify the existing ones exclusively via the Figma plugin. However, you are free to export the translations in any way you desire. In this example (and most commonly overall), we'll use CLI so that the developers can use the content directly in the code.
🎨 Preparing Content in Figma
Configure the plugin
First, open a file of your choice in Figma, initialize the Localazy Figma plugin, and connect to your target Localazy project.
Then in the Plugin's settings, I'll check Use node name as source key for more readable source keys (instead of Figma's internal numerical IDs) and uncheck Upload & download the entire file to only upload text nodes I have currently selected. I will also upload screenshots to Localazy since they offer valuable context for the translators, and the Figma plugin will automatically link the keys with the uploaded screenshots.
Upload the content
Let's follow this whole workflow from the design stage to using the keys in code from the perspective of a task. In an agile environment, each task should contain a detailed specification, and ideally, a single person should be assigned at a time to prevent confusion about responsibilities. Each stage (design, translation, development) can be either a subtask or just a list item within the task.
Let's say the design is over, and the task is now assigned to a localization manager. Their first job is to go through the textual nodes in designs and rename the nodes so that the source keys uploaded in Localazy have more readable and understandable names.
The next step is to upload the content into the appropriate file. The target file format, file name, and file path will depend on the development team's requirements. Discuss this step before you adopt this workflow. In our simplified example, we will upload all the content into a single file called figma in JSON format, which could work for some teams but not for everyone.
So, select the target layouts and upload them.
🚩 Translate in Localazy
The new content has been successfully uploaded to Localazy, and the task moves on to translators. If you seek professional quality translations, either invite your in-house translators or order the translations from our professional translators. Since we've uploaded screenshots along with the content, the quality of translations would likely improve, thanks to the extra context. Bravo!
However, to speed things up, we'll add just a few languages and translate them via MT. For each language, open the options dropdown and select Pre-translate with MT.
In the next step, feel free to choose your favorite MT engine. Each can handle specific scenarios, terms, and tonality differently, and one cannot say one is always better.
I'll go with DeepL for demonstration purposes since their API can generally handle the translation request quite swiftly, and the translation quality is usually satisfactory. Make sure to check the option Approve all translations so that you can use them immediately without having to review and accept them afterward. Check the other options so that they are pre-selected next time, which assures that all the keys will always be included in the pre-translate operation.
It could take a few seconds, but after a few page refreshes, you should see all three languages fully translated.
🌍 Use the translations
Preview in Figma
Before handing over the new designs for development, importing the translations to Figma may be beneficial to ensure your designs are robust enough to handle different languages.
We hand the task back to designers, who will preview the translations in different languages. Go back to your Figma file and switch to the Download tab in the Localazy Figma plugin. Select the source file and desired language, and select the screen/nodes you've uploaded to Localazy previously.
Figma design translated into German with LocalazyAwesome, we have the design translated into German in just a few minutes. And we can also see that some labels are a little too long and almost overflow the container. Yikes! 🙈 Here, we can see the benefit of previewing the translations directly in Figma. Since the development hasn't started, we have saved time and money.
With Arabic, it gets more complicated. Not only because there is also some overflowing text but also because it is a right-to-left written language. The Figma plugin does not automatically change the text alignment, so you still need to tweak the design manually. But it's definitely much less work than having to translate the whole design as well.
Figma design translated into Arabic with LocalazyOnce the designers iterate over the designs, the task is assigned back to the localization manager, who again assures that all the keys have readable names. If there have been changes in values, the translators will take over again. Feel free to bounce between designers, localization managers, and translators as long as there is something to update.
Use the content in the code
Eventually, the developer is assigned to the task, and the actual implementation may commence. We'll go through a first-time setup together. From the second time onwards, this part is much more straightforward.
Go to the Translations page and open Select an integration.
Look up the type of framework, programming language, or file format you're using and choose the CLI integration method.
After you install the Localazy CLI tool and create localazy.json in the root of your project, we'll need to modify the initial template to suit our needs and the herein-described workflow.
Since we don't want to allow uploading anything from outside the Figma plugin, we'll delete the writeKey and the upload block completely. We also include the source language in the downloaded batch. For further configuration options, see the CLI documentation.
{
"readKey": "<YOUR-READ-KEY>",
"download": {
"includeSourceLang": true,
"files": "translations/${fullPath}/${lang}.json"
}
}I will keep it simple and download all content into the translations folder, where the keys will reside in folders named after, like the files in Localazy (figma in our case). Each JSON file will be named after the language's locale code.
Your development team should sit down with you and discuss this part before you start adopting this Figma workflow. There are dozens and dozens of ways developers organize localization assets, and this is just one example.
Once you adjust the configuration to your needs, run the localazy download command via CLI. A viola!
All the translations and source keys have been successfully imported, and the developers can start using them. They should have access to the Figma designs so that:
- They know what they are implementing 😁
- And they can look up the keys in designs that the localization manager renamed for them. We've come a full circle 🙂
⚖️ Pros and cons
➕ Pros
- There is a tight connection between the textual content in Figma designs and the actual product content.
- Designers don't need to do anything extra (unless they are the ones renaming the source keys and uploading the content). On the contrary, they may easily preview the content in other languages.
- Translators can use the linked screenshots to provide better-quality translations.
- Iterating over older designs is quicker, and designers work with accurate content.
➖ Cons
- It takes some time to discuss and set up properly. Afterward, it takes time for everyone to get used to this workflow.
- It is beneficial to have a localization manager who manages uploading the content to Localazy and everything else that is related to management in Localazy itself. I.e., somebody needs to be responsible for it.
- When developers find a missing source key in the designs, it takes multiple steps before the updated content makes it to the code. If this happens often, it slows down the development quite a bit.
- The management aspects of this workflow are more complicated in comparison to other Figma workflows.
✔️ Closing word
If you've made it all the way here, congratulations! I bet you're telling yourself that this is quite a complicated workflow. It is. However, once all the teams finish the one-time configuration steps and thoroughly discuss and agree on the workflow, it becomes quite smooth. And the reward is a truly tight connection between the designs and the product. And if you tend to return to older parts of your product and update it, you can trust me that all the efforts will be deemed worth it.
Be sure to check more articles from the series about common Figma plugin workflows.
This is a companion discussion topic for the original entry at https://localazy.com/blog/figma-series-figma-as-source-of-truth