> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Localization

## Article: Localization

## Article Link: https://dev.wix.com/docs/wix-design-system/guidelines/localization.md

## Article Content:

<!-- heading -->

# Localization

<!-- end heading -->

## What is localization

Localization is the process of adapting a product to a specific country or region, in terms of both language and culture. In other words, our goal is to have every interface, flow, and feature translated and adapted to the user's needs. Essentially, each area of the product should be customized for users in their specific locations.

### Localization-friendly design
* Accommodates different text lengths in all product components.  
* Supports various grammatical structures.  
* Includes comments for front-end developers regarding formats pulled from libraries to ensure localization is supported.  
* Avoids images containing text, as well as culture- or region-specific design elements.

![Localization-friendly design](https://wixmp-833713b177cebf373f611808.wixmp.com/images/790143ab92d26b997b166a8964e51a0c.png)

## Localization cheatsheet

Each language has a unique structure, rules, special symbols, and alphabet. The word order and text length change according to each language. Additionally, the height of letters varies across alphabets (for example, Japanese, Chinese, Korean). Therefore, our designs shouldn't be based solely on English but should consider all Wix-supported languages and their requirements.

![Localization cheatsheet](https://wixmp-833713b177cebf373f611808.wixmp.com/images/21833cc736dc51bac93284308ac36c41.png)

### Text expansion guides

Localized content often expands. Text in most languages is on average **50% longer than English**. Non-Latin languages, such as Japanese, tend to take up more vertical space. The design must be flexible enough to accommodate these changes without altering the context of use. We recommend **testing designs with different languages** before the development phase.

**Always account for worst-case scenarios in text length.** Most languages are longer than English, potentially expanding components significantly.
  
Examples:
* "Upgrade" (English) vs. "Fazer upgrade" (Portuguese)  
* "Add" (English) vs. "Toevoegen" (Dutch)  
* "Edit" (English) vs. "Bearbeiten" (German) or "Редагувати" (Ukrainian)

![Text expansion guides](https://wixmp-833713b177cebf373f611808.wixmp.com/images/b6fbd9bf54e727586e152edc30bbd8cc.png)

###  Avoid truncating text by design

While all components are equipped to handle edge cases by truncating text and displaying the full content on hover, this should only serve as a fallback rather than a primary solution. Relying on ellipses decreases discoverability and may lead to user frustration, especially in longer languages, where truncation can occur in multiple places on the same screen.

![Avoid truncating text by design](https://wixmp-833713b177cebf373f611808.wixmp.com/images/f547b5e591071237bf430be8bab795de.png)

### Break text into several lines 
Allow component  labels, text links, bullet points and other text elements to overflow onto the next line. Use line breaks or consider using icons instead of words when applicable, but keep in mind that text buttons have a much better discoverability.

<!-- dodont group -->
<!-- dodont -->
<!-- dodont image -->
![Do: when possible, use line breaks for labels. In most cases, text in English that fills one row expands to two or three rows in other languages](https://wixmp-833713b177cebf373f611808.wixmp.com/images/b25d900ecee7895d17749f0caa015599.png)


<!-- end dodont image -->
<!-- dodont content -->


#### Do

When possible, use line breaks for labels. In most cases, text in English that fills one row expands to two or three rows in other languages.
<!-- end dodont content -->
<!-- end dodont -->
<!-- dodont -->
<!-- dodont image -->
![Don't: rely on tooltips on ellipsis. Always assume the text takes more than one row](https://wixmp-833713b177cebf373f611808.wixmp.com/images/91dff7091feaff99e6d028d51478840f.png)

<!-- end dodont image -->
<!-- dodont content -->


#### Don't

Don't rely on tooltips on ellipsis. Always assume the text takes more than one row. 
<!-- end dodont content -->
<!-- end dodont -->
<!-- end dodont group -->

Allow text to break into a second line, regardless of which component wrapper they are in, if it's a tooltip or a card, the component should grow with the content.

### Layout in panels 

Panels have a fixed width of 288px, so it is important to make sure that all of the elements are stacked correctly to support content in different languages.

<!-- dodont group -->
<!-- dodont -->
<!-- dodont image -->
![Do: you can use a text element and an \<IconButton/\> side-by-side](https://wixmp-833713b177cebf373f611808.wixmp.com/images/e4f7a835be9c5a02abf47d38fd9535fa.png)


<!-- end dodont image -->
<!-- dodont content -->


#### Do

You can use a text element and an \<IconButton/\> side-by-side. 
<!-- end dodont content -->
<!-- end dodont -->
<!-- dodont -->
<!-- dodont image -->
![Don't: avoid positioning two text elements next to each other, side-by-side](https://wixmp-833713b177cebf373f611808.wixmp.com/images/cc9c2d03d8e520ae2b52b39a7c6e734b.png)

<!-- end dodont image -->
<!-- dodont content -->


#### Don't

Avoid positioning two text elements next to each other, side-by-side.  
<!-- end dodont content -->
<!-- end dodont -->
<!-- end dodont group -->

<!-- dodont group -->
<!-- dodont -->
<!-- dodont image -->
![Do: position text labels above other elements. Use <FormField/> wrappers to control the positioning of labels](https://wixmp-833713b177cebf373f611808.wixmp.com/images/6b387e952f0bbc9b2d9f80ac1e09a291.png)


<!-- end dodont image -->
<!-- dodont content -->


#### Do

Position text labels above other elements. Use <FormField/> wrappers to control the positioning of labels.
<!-- end dodont content -->
<!-- end dodont -->
<!-- dodont -->
<!-- dodont image -->
![Don't: avoid having text labels on the side of other elements. They overlap the element beside them, or cut off with an ellipsis in longer languages](https://wixmp-833713b177cebf373f611808.wixmp.com/images/64f696ec6cf6993d33faaea2bdd4de5e.png)

<!-- end dodont image -->
<!-- dodont content -->


#### Don't

Avoid having text labels on the side of other elements. They overlap the element beside them, or cut off with an ellipsis in longer languages.
<!-- end dodont content -->
<!-- end dodont -->
<!-- end dodont group -->

### Thumbnails in panels

<!-- dodont group -->
<!-- dodont -->
<!-- dodont image -->
![Do: use up to 3 thumbnails in a row. Be sure the labels on the thumbnails wrap into multiline](https://wixmp-833713b177cebf373f611808.wixmp.com/images/5a22474a4f64b524d4284fbba1b5edaa.png)


<!-- end dodont image -->
<!-- dodont content -->


#### Do

Use up to 3 thumbnails in a row. Be sure the labels on the thumbnails wrap into multiline. 
<!-- end dodont content -->
<!-- end dodont -->
<!-- dodont -->
<!-- dodont image -->
![Don't: avoid using more than 3 thumbnails in a row. If there are more, the labels tend expand and overlap. Don't rely on ellipses and tooltips to show a full label](https://wixmp-833713b177cebf373f611808.wixmp.com/images/de0bebe27c4c3a5d6a6a207f7a6af855.png)

<!-- end dodont image -->
<!-- dodont content -->


#### Don't

Avoid using more than 3 thumbnails in a row. If there are more, the labels tend expand and overlap. Don't rely on ellipses and tooltips to show a full label.
<!-- end dodont content -->
<!-- end dodont -->
<!-- end dodont group -->

### Avoid UI components to build sentences 

As every language has a different grammatical structure, the order of words in a sentence can vary. 

<!-- dodont -->
<!-- dodont image -->
![Don't: build sentences from UI components that have a hardcoded structure](https://wixmp-833713b177cebf373f611808.wixmp.com/images/b1b4f23c3a6d7c2b9b87b47ecdb34daf.png)
<!-- end dodont image -->
<!-- dodont content -->
#### Don't
Don't build sentences from UI components that have a hardcoded structure.
<!-- end dodont content -->
<!-- end dodont -->

In most cases layout can be redesigned to work in all languages, without having to develop different versions of the same product for different languages. 

<!-- dodont -->
<!-- dodont image -->
![Do: adjust layouts and copy to work in every language and region](https://wixmp-833713b177cebf373f611808.wixmp.com/images/b7a9f7efedb6b0eb1fa9a19682dd0e7d.png)
<!-- end dodont image -->
<!-- dodont content -->
#### Do
Adjust layouts and copy to work in every language and region.   
<!-- end dodont content -->
<!-- end dodont -->

### Dates and numbers

When dates and time are used in design, consider that there are different formats for each language and country. These values should never be hardcoded. For example, in \<DatePicker/\> component a property called "locale" is available to help handle different formats. 
![Dates and numbers](https://wixmp-833713b177cebf373f611808.wixmp.com/images/e690e3e7928e3006d0553d02752983c9.png)

### Text on images and illustrations

In general, it's not recommended to have any text in images or illustrations. Visuals should'nt include text. However if it must, text should be blurred or there should be different versions for each language (that means over 20 versions).  This is valid for marketing pages and other promotional materials. 

<!-- dodont group -->
<!-- dodont -->
<!-- dodont image -->
![Do: blur text or use shapes instead](https://wixmp-833713b177cebf373f611808.wixmp.com/images/2f45b8b500bf9d81fae2f1227a8a09f5.png)


<!-- end dodont image -->
<!-- dodont content -->


#### Do

Blur text or use shapes instead.
<!-- end dodont content -->
<!-- end dodont -->
<!-- dodont -->
<!-- dodont image -->
![Don't: add any text to images or illustrations](https://wixmp-833713b177cebf373f611808.wixmp.com/images/1b9f8ae5f9a6c506e7f46ed6deacb79b.png)

<!-- end dodont image -->
<!-- dodont content -->


#### Don't

Don't add any text to images or illustrations  
<!-- end dodont content -->
<!-- end dodont -->
<!-- end dodont group -->


### QA your product

Always make sure your design and product is localized correctly starting from the design phase and in development. Any later layout changes can affect localization as well. For any additional requests, reach out to your localization manager and arrange a review.   
Reviewing your designs with a localization manager early saves a lot of time later. If needed, reach out to the localization team on [#localization](https://wix.slack.com/archives/C038F653GTX) Slack channel.