block / block/berd

Add Japanese UI localization

Open
#180 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
909
Forks
116
Avg merge
1d 1h
Merged PRs (30d)
156

Description

### Before filing

- [x] I searched [open and closed issues](https://github.com/block/berd/issues?q=is%3Aissue) for duplicates.
- [x] I am using the current release, Berd v0.6.2, and this doesn't already exist.
- [x] This is one request, not several bundled together.

### Closest existing issue

None found. I searched open and closed issues for Japanese, 日本語, i18n, localization, locale, and translation. #101 concerns right-to-left layout rather than Japanese localization.

### Is this new, or an improvement?

New capability — Berd can't do this at all today.

### The problem, in your terms

I use Berd in a Japanese-language environment, but its menus, settings, onboarding, dialogs, and messages are only available in English or Spanish. This adds continual translation overhead and makes the app less approachable for Japanese-speaking users, especially during setup and when interpreting errors or permission-sensitive actions.

Berd already detects the system locale, but a `ja-JP` system currently falls back to English because Japanese is not a supported app locale.

### What you do today

I keep Berd in English and translate unfamiliar interface text manually. There is no skill, agent, extension, or automation that can localize Berd's own application chrome.

### What you'd like to see

Add Japanese (`ja`) as a supported UI locale and make it available in **Settings → General → Language**. When the language preference is set to “System default,” `ja-JP` and other Japanese system locale variants should resolve to Japanese.

The existing i18n architecture appears ready for this: register `ja`, add the Japanese lazy resource loaders, and provide Japanese catalogs for the existing translation namespaces. Dates, numbers, relative time, the document `lang` attribute, explicit preference persistence, and English fallback should continue using the current locale infrastructure.

Translation catalogs should preserve interpolation placeholders, plural keys, newlines, URLs, and technical identifiers. Automated checks for English/Japanese key and placeholder parity would help prevent drift.

### Why this belongs in Berd itself

This affects Berd's native menus, settings, onboarding, dialogs, toasts, and accessibility metadata before and outside any agent session. Skills, agents, extensions, and automations cannot replace the renderer's built-in translation resources or make locale detection and the language selector support Japanese. It therefore needs to be part of Berd's core i18n setup.

### Non-goals

- This request is not for translating agent-generated responses or user-authored content.
- It does not request machine translation at runtime or a new translation service/dependency.
- It does not request changes to model/provider language behavior.
- It does not include right-to-left layout work; Japanese is left-to-right, and RTL support is tracked separately in #101.
- It does not require Japanese installer localization as part of the first iteration.

### Alternatives you considered

- **Keep using the English UI:** workable, but it creates recurring friction and does not help users who are not comfortable reading English.
- **Use a translation skill or agent:** rejected because those cannot translate Berd's own application chrome or setup screens.
- **Maintain a private fork:** technically possible, but translations would drift as the product evolves and would not benefit the broader Japanese-speaking user base.

### Mockups, prior art, or other context

Berd already ships English and Spanish catalogs under `src/shared/i18n/locales/` and has locale detection, persistence, lazy loading, and `Intl`-based formatting. Japanese can follow that established pattern without introducing a parallel localization system.

Contributor guide

Open the contributing guide

Research direction

Start by inspecting the existing English and Spanish catalogs under src/shared/i18n/locales/ and the locale detection, persistence, lazy-loading, and language-selector paths that use them. Register ja and add Japanese resources for the existing namespaces, preserving placeholders and plural keys; done means Japanese settings selection and Japanese system locales work with English fallback and parity checks prevent missing keys.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
internationalization, localization
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.