Custom locales: shipping やさしい日本語 (Easy Japanese) alongside your standard languages

Most i18n tooling assumes every language fits a two-letter code. Real products sometimes need more. We recently got a question from a team whose product ships in Japanese, and in Easy Japanese for users still learning the language. Their locale is ja_easy.

What is やさしい日本語 (Easy Japanese)?

やさしい日本語 is a standardized plain-language register of Japanese, developed for residents who are not yet fluent: immigrants, foreign workers, exchange students. Japanese government agencies publish official guidelines for it: short sentences, everyday vocabulary, hiragana-friendly spelling, no honorific keigo.

It is not a dialect and not a translation shortcut. It's a deliberate version of Japanese, written for a specific audience. If your product serves language learners or new residents in Japan, it may well be your most important locale.

There's no ISO code for it. So teams pick their own, like ja_easy, and most localization tools then reject it outright or silently skip the files.

We've added support for custom locales

This is a first version, and a feature we're actively exploring. Here's how it works today: you declare the locale when setting up your project with localhero init, giving it a name and the base language it builds on. It lands in localhero.json like this:

{
  "sourceLocale": "en",
  "outputLocales": ["ja", "ja_easy", "vi", "th"],
  "customLocales": [
    { "code": "ja_easy", "name": "Easy Japanese", "baseLanguage": "ja" }
  ]
}

That's the whole setup. From there, ja_easy behaves like any other language:

• config/locales/ja_easy.yml is picked up by file scanning, push, pull, and CI, including namespaced files like devise.ja_easy.yml
• The base language drives the linguistic machinery: plural rules, the 🇯🇵 flag in the dashboard, language-specific translation guidance
• Your existing Easy Japanese copy imports as-is. We treat it as its own content, not as a translation of your English
• Translations show up for human review per pull request, like every other locale

The declaration matters. We deliberately don't blanket-accept unknown codes, because a typo like jp should fail loudly instead of quietly creating a broken language. Declaring customLocales is what tells us this one is real, and here is what it means.

What AI translation into Easy Japanese looks like

While looking into this, we dug into the やさしい日本語 guidelines and tuned our translation engine to understand the style. So when translating into Easy Japanese you don't just get Japanese: you get hiragana-leaning spelling with 分かち書き spacing, vocabulary a JLPT N4-N5 learner knows, polite です・ます form without keigo, and loanwords kept in katakana the way Japanese actually writes them.

The same source string, Try the exam again, side by side:

We keep this honest with automated evals: a test suite asserts the register holds: katakana loanwords never degrade into hiragana, no keigo slips in, and ambiguous spellings like きのう (which can read as feature or yesterday) get resolved properly. AI translation of a register is only useful if it's consistent.

And if you'd rather write Easy Japanese yourself and only use Localhero for review, that works too. Custom locales don't force AI translation on you.

Your product, your locales

Sometimes languages in real products don't match tidy standard lists. We want Localhero to work great for what your product actually needs, and custom locales are part of that: you define the language versions that matter to your users, and the platform treats them like any other locale. That said, when a standard code exists, sticking to it is usually the right call. Custom locales are for the cases the standards don't cover.

If you're building for language learners, new residents, or any audience that standard locale codes don't describe: this is a supported path, not a workaround.

We're also genuinely curious how teams handle this today. If you ship a simplified-language version of your product, like やさしい日本語, Leichte Sprache or plain English, or you've wanted to and your tooling got in the way, we'd love to talk and learn how you solve it: hi@localhero.ai.