New May 12, 2025

Integrating Localization Into Design Systems

The Giants All from Articles on Smashing Magazine — For Web Designers And Developers View Integrating Localization Into Design Systems on smashingmagazine.com

Mark and I work as product designers for SAS, a leader in analytics and artificial intelligence recognized globally for turning data into valuable insights. Our primary role is to support the token packages and component libraries for the SAS Filament Design System. SAS’ customer base is global, meaning people from diverse countries, cultures, and languages interact with products built with the Filament Design System.

SAS designers use Figma libraries developed by the Filament Design System team to create UX specifications. These high-fidelity designs are typically crafted in English, unknowingly overlooking multilingual principles, which can result in layout issues, text overflow, and challenges with right-to-left (RTL) languages. These issues cascade into the application, ultimately creating usability issues for SAS customers. This highlights the need to prioritize localization from the start of the design process.

With the introduction of Figma Variables, alongside the advancements in design tokens, we saw an opportunity for designers. We imagined a system where a Figma design could dynamically switch between themes, densities, and even languages.

This would allow us to design and test multilingual capabilities more effectively, ensuring our design system was both flexible and adaptable.

While researching localization integration for design systems, we realized a significant gap in existing documentation on supporting localization and internationalization in design tokens and Figma Variables. Many of the challenges we faced, such as managing typography across locales or adapting layouts dynamically, were undocumented or only partially addressed in available resources.

Our story demonstrates how combining foundational principles of multilingual design with design tokens can help tackle the complexities of language switching in design systems. We are not arguing that our approach is the best, but given the lack of documentation available on the subject, we hope it will get the conversation started.

But before we start, it’s essential to understand the distinction between Localization (L10n) and Internationalization (I18n).

Localization (L10n) refers to the process of adapting designs for specific languages, regions, or cultures and involves the following:

Internationalization (I18n) is the preparation phase, ensuring designs are flexible and adaptable to different languages and regions. Key considerations in Figma include:

These concepts are not only foundational to multilingual design but also integral to delivering inclusive and accessible experiences to global users.

Pre-Figma Setup: Building A Framework

Understanding Our Design Token System

Before diving deeper, it’s crucial to understand that our design tokens are stored in JSON files. These JSON files are managed in an application we call “Token Depot,” hosted on our corporate GitHub.

We utilize the Tokens Studio plugin (pro plan) to transform these JSON files into Figma libraries. For us, design tokens are synonymous with variables — we don’t create additional variables that only exist in Figma. However, we do create styles in Figma that serve as “recipe cards” for specific HTML elements. For instance, an H2 might include a combination of font-family, font-size, and font-weight.

It’s important to note that our design token values are directly tied to CSS-based values.

Initial Setup: Theme Switching And Localization

In 2022, we took on the massive task of refactoring all our token names to be more semantic. At that time, we were only concerned with theme switching in our products.

Our tokens were re-categorized into the following groups:

In our early setup:

Our JSON files were configured with English as the default. Other locales were managed with a set of JSON files that included overrides for English. These overrides were minimal, focusing mainly on font and typography adjustments. For example, bold typefaces often create issues because many languages like Chinese, Japanese, or Korean (CJK languages) fonts lack distinct bold versions. Thus, we replaced the font-weight token value from 700 to 400 in our CJK locales.

We also update the values for font-family, letter spacing, font-style, and font-variant tokens. In Figma, our application screens were originally designed in English, and in 2023, we only implemented theme-switching modes, not language options. Additionally, we created detailed lists to document which design tokens could be converted to Figma variables and which could not, as the initial release of variables supported only a limited set.

Introducing Density Switching

The introduction of density switching in our products marked a significant turning point. This change allowed us to revisit and improve how we handled localization and token management. The first thing we had to figure out was the necessary token sorting. We ended up with the following list:

Tokens Impact By Theme And Density

Unaffected by Theme or Density:

Tokens Impacted by Density:

Tokens Impacted by Theme:

With density, we expanded locale-specific value changes beyond font-family, letter spacing, font-style, and font-variant tokens to additionally include:

Revisiting our type scale and performing numerous calculations, we documented the required token value changes for all the locales across the density. This groundwork enabled us to tackle the restructuring of our JSON files effectively.

JSON File Restructuring

In our token repository, we:

  1. Updated the tokens in the core folder.
  2. Added a density folder and a language folder in each brand.

After collaborating with our front-end development team, we decided to minimize the number of JSON files. Too many files introduce complexity and bugs and hinder performance. Instead of creating a JSON file for each language-density combination, we defined the following language categories:

Language Categories

These categories became our JSON files, with one file per density level. Each file contained tokens for font size, icon size, line height, spacing, and border-radius values. For example, all Chinese locales shared consistent values regardless of font-family.

In addition, we added a folder containing JSON files per locale, overriding core values and theme folders, such as font-family.

Figma Setup: Bridging Tokens And Design

Token Studio Challenges

After restructuring our JSON files, we anticipated gaining support for typography variables in the Tokens Studio plugin. Instead, Tokens Studio released version 2.0, introducing a major shift in workflow. Previously, we imported JSON files directly into Figma and avoided pushing changes back through the plugin. Adjusting to the new version required us to relearn how to use the plugin effectively.

Our first challenge was navigating the complexity of the import process. The $metadata.json and $themes.json files failed to overwrite correctly during imports, resulting in duplicate collections in Figma when exporting variables. Despite recreating the required theme structure within the plugin, the issue persisted. To resolve this, we deleted the existing $metadata.json and $themes.json files from the repository before pulling the updated GitHub repo into the plugin. However, even with this solution, we had to manually remove redundant collections that appeared during the export process.

Once we successfully migrated our tokens from JSON files into Figma using the Tokens Studio plugin, we encountered our next challenge.

Initially, we used only “English” and theme modes in Figma, relying primarily on styles since Figma’s early variable releases lacked support for typography variables. Now, with the goal of implementing theme, density, and language switching, we needed to leverage variables — including typography variables. While the token migration successfully brought in the token names as variable names and the necessary modes, some values were missing.

Typography variables, though promising in concept, were underwhelming in practice. For example, Figma’s default line-height multiplier for “auto” was 1.2, below the WCAG minimum of 1.5. Additionally, our token values used line-height multipliers, which weren’t valid as Figma variable values. While a percentage-based line-height value is valid in CSS, Figma variables don’t support percentages.

Our solution involved manually calculating pixel values for line heights across all typography sizes, locale categories, and densities. These values were entered as local variables in Figma, independent of the design token system. This allowed us to implement correct line-height changes for density and locale switches. The process, however, was labor-intensive, requiring the manual creation of hundreds of local variables. Furthermore, grouping font sizes and line heights into Figma styles required additional manual effort due to the lack of support for line-height multipliers or percentage-based variables.

Examples:

Additional Challenges

Starting with a Western font ensured proper rendering of Latin characters and symbols while maintaining brand consistency. However, Figma’s designs using only AnovaUI (SAS Brand Custom font) couldn’t preview locale-based substitutions via system fonts, complicating evaluations of mixed-content designs.

Finally, as we prepared to publish our new library, we encountered yet another challenge: Figma Ghosts.

What Are Figma Ghost Variables?

Figma “ghost variables” refer to variables that remain in a Figma project even after they are no longer linked to any design tokens, themes, or components.

These variables often arise due to incomplete deletions, improper imports, or outdated metadata files. Ghost variables may appear in Figma’s variable management panel but are effectively “orphaned,” as they are disconnected from any meaningful use or reference.

Why They Cause Issues for Designers:

Addressing ghost variables requires careful management of design tokens and variables, often involving clean-up processes to ensure only relevant variables remain in the system.

Cleaning Up Ghost Variables

To avoid the issues in our Figma libraries, we first had to isolate ghost variables component by component. By selecting a symbol in Figma and navigating the applied variable modes, we had a good sense of which older versions of variables the symbol was still connected to. We found disconnected variables in the component library and our icon library, which resulted in compounded ghost variables across the system. We found that by traversing the layer panel, along with a fantastic plug-in called “Swap Variables,” we were able to remap all the ghost variables in our symbols.

If we had not completed the clean-up step, designers would not be able to access the overrides for theme, density, and locale.

Designing Symbols For Localization

To ensure Figma symbols support language swapping, we linked all text layers to our new variables, including font-family, font-size, and line height.

We do not use Figma’s variable feature to define text strings for each locale (e.g., English, Spanish, French) because, given the sheer breadth and depth of our Products and solutions, it would simply be too daunting a task to undertake. For us, using an existing plug-in, such as “Translator,” gives us what we need.

After ensuring all text layers were remapped to variables, along with the “Translator” plug-in, we were able to swap entire screens to a new language. This allowed us to start testing our symbols for unforeseen layout issues.

We discovered that some symbols were not supporting text wrapping when needed (e.g., accommodating longer words in German or shorter ones in Japanese). We isolated those issues and updated them to auto-layout for flexible resizing. This approach ensured all our Figma symbols were scalable and adaptable for multilingual support.

Delivering The System

With our component libraries set up to support localization, we were ready to deliver our component libraries to product designers. As a part of this step, we crafted a “Multilingual Design Cheat Sheet” to help designers understand how to set up their application mockups with Localization and Internationalization in mind.

Multilingual Design Cheat Sheet:

  1. General Principles
    • Design flexible layouts that can handle text wrapping and language-specific requirements such as right-to-left orientations.
    • Use real content during design and development to identify localization issues such as spacing and wrapping.
    • Research the cultural expectations of your target audience to avoid faux pas.
  2. Text & Typography
    • Use Filament Design Systems fonts to ensure support of all languages.
    • Avoid custom fonts that lack bold or italic styles for non-Latin scripts like CJK languages.
    • Reserve additional space for languages like German or Finnish.
    • Avoid hardcoded widths for text containers and use auto-layout to ensure long text strings are readable.
    • The Filament Design System tokens adjust line height per language; make sure you are using variables for line-height.
    • Use bold sparingly, as Filament tokens override bold styling in some languages. Instead, opt for alternative emphasis methods (e.g., color or size).
  3. Layout & Design
    • Mirror layouts for RTL languages (e.g., Arabic, Hebrew). Align text, icons, and navigation appropriately for the flow of the language.
    • Use auto-layout to accommodate varying text lengths.
    • Avoid embedding text in images to simplify localization.
    • Allow ample spacing around text elements to prevent crowding.
  4. Language-Specific Adjustments
    • Adapt formats based on locale (e.g., YYYY/MM/DD vs. MM/DD/YYYY).
    • Use metric or imperial units based on the region.
    • Test alignments and flows for LTR and RTL languages.
  5. Localization Readiness
    • Avoid idioms, cultural references, or metaphors that may not translate well.
    • Provide space for localized images, if necessary.
    • Use Figma translation plug-ins to test designs for localization readiness and use real translations rather than Lorem Ipsum.
    • Test with native speakers for language-specific usability issues.
    • Check mirrored layouts and interactions for usability in RTL languages.
Lessons Learned And Future Directions

Lessons Learned

In summary, building a localization-ready design system was a complex yet rewarding process that taught Mark and me several critical lessons:

Future Directions

As we look ahead, our focus is on enhancing the Filament Design System to better support global audiences and simplify the localization process for designers:

Through these efforts, Mark and I hope to create a more inclusive, scalable, and efficient design system that meets the diverse needs of our global audience while empowering SAS designers to think beyond English-first designs.

Further Reading On SmashingMag

Scroll to top