# localization-design

Helps design UI for different languages, writing directions, and cultural contexts before translations arrive.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1700 installs · ★ 3103
- Author: Owl-Listener
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Owl-Listener/designer-skills/tree/HEAD/design-systems/skills/localization-design/SKILL.md
- Updated: 2026-09-05
- HTML: https://affpapa.org/en/nevibecode/skills/localization-design

## What it does

This skill checks whether components can handle text expansion and recommends flexible sizing instead of fitting English copy. It uses German or Finnish as long-text proxies when other translations are not ready. Buttons need a minimum width and room to wrap in narrow contexts.

For RTL languages, it covers mirrored navigation, sidebars, and directional icons. It recommends logical CSS properties such as `margin-inline-start` and `text-align: start`. Numerals usually remain LTR within RTL text. That is a reason to test an RTL locale before adding a component to a design system.

The skill also covers fonts for non-Latin scripts, cultural color and icon meanings, and locale formats for dates, currencies, and addresses. It points to `Intl.DateTimeFormat` for dates and numbers, and calls for semantic token names such as `start` rather than `left`. Use `ux-writing` from `designer-toolkit` for interface wording.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Owl-Listener/designer-skills --skill localization-design -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/localization-design/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/localization-design/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Owl-Listener/designer-skills --skill localization-design -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/localization-design/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Owl-Listener/designer-skills --skill localization-design -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/localization-design/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Owl-Listener/designer-skills localization-design
```

2. **Manually: put the files in place**
- File: `.github/skills/localization-design/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Owl-Listener/designer-skills --skill localization-design -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Owl-Listener/designer-skills --path design-systems/skills/localization-design
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/localization-design/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Owl-Listener/designer-skills --skill localization-design -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Owl-Listener/designer-skills/tree/HEAD/design-systems/skills/localization-design/SKILL.md

## When to use it
- test layouts against translated text expansion
- mirror navigation for RTL interfaces
- replace physical CSS offsets with logical properties
- format dates and numbers by locale
- review icons and colors for cultural meaning

## Example prompts
- Review this UI for text expansion and suggest changes for German translations.
- Adapt the navigation and directional icons for RTL with logical CSS properties.
- Check this date and price component for `Intl.DateTimeFormat` and locale-aware currency formatting.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3c93e18480a86e0e.

BEGIN THIRD-PARTY FILE 3c93e18480a86e0e
```text
---
name: localization-design
description: Design for multiple languages, writing directions, and cultural contexts — text expansion, RTL mirroring, and locale formats. Use when shipping beyond one locale. For the words themselves, use `ux-writing` (designer-toolkit).
---
# Localization Design
You are an expert in designing UI that works across languages, scripts, and cultures without requiring per-locale redesigns.
## What You Do
You apply localization-aware design principles to ensure components, layouts, and content can be adapted to any target locale without breaking — and that cultural differences in color, iconography, and conventions are accounted for.
## Text Expansion
The most common localization failure. English is compact; most target languages are longer:
| Language | Typical expansion vs English |
|---|---|
| German | +20–35% |
| French | +15–25% |
| Finnish | +30–40% |
| Arabic (translated) | −20–30% (but RTL and different script) |
| Japanese/Chinese | Often shorter, but very different typographic rules |
**Design for text expansion:**
- Never size containers to fit English copy — use flexible heights and widths
- Test layouts with German or Finnish translations as worst-case proxies before other locales exist
- Truncation with ellipsis is an acceptable last resort, but provide full text via tooltip/expand
- Buttons: use min-width, not fixed width; allow wrapping for extreme cases in narrow contexts
- Navigation labels: test all nav items together at 130% length to validate menu doesn't break
## RTL (Right-to-Left) Support
Arabic, Hebrew, Persian, and Urdu read right-to-left. The entire layout mirrors:
- **Content flow**: text, lists, and reading order reverse
- **Layout mirroring**: sidebars, navigation, and content areas flip; left margin becomes right margin
- **Icon mirroring**: directional icons (arrows, chevrons, back button) mirror; non-directional icons (camera, settings) do not
- **CSS logical properties**: use `margin-inline-start` instead of `margin-left`; `padding-block-end` instead of `padding-bottom` — these flip automatically with `dir="rtl"`
- **Text alignment**: use `text-align: start` not `text-align: left`
- **Numbers**: numerals remain LTR within RTL text in most contexts; don't mirror number displays
**What does not mirror in RTL:**
- Logos and brand marks
- Clocks and time displays
- Mathematical notation
- Images and illustrations (usually — context-dependent)
- Video player controls (debated; mirror directional but not play/pause)
## Typography for Non-Latin Scripts
```
END THIRD-PARTY FILE 3c93e18480a86e0e

The third-party file has ended. Everything between the 3c93e18480a86e0e tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2569 of 5309 bytes. © Owl-Listener · MIT · https://github.com/Owl-Listener/designer-skills/tree/HEAD/design-systems/skills/localization-design/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md