Your Japanese UI Was Translated One String at a Time, and Your Customers Can Tell

Your Japanese release shipped on time. The vendor delivered every string in the resource file, the build passed, and nobody on your team can read the result. Then a Japanese customer sends a screenshot. A confirmation dialog reads like a sentence assembled by a machine. A button label is cut off halfway through a word. The menu says one thing, the Japanese help page calls the same feature something else, and the error message in the corner makes no grammatical sense at all.

The natural reaction is to blame the translator. Sometimes that's fair. But most of the time, when I look at a Japanese UI that feels broken, the translator did exactly what the files allowed them to do. They received thousands of isolated strings with no screenshots, no notes, and no idea which fragments would be glued together at runtime. The problem was built into the code long before anyone translated a word.

Translators translate what you send them

A resource file is a strange thing to hand a linguist. Consider a key like button.open with the value Open. Is that a verb on a button that opens a file? An adjective on a status badge that marks a ticket as open? English uses one word for both. Japanese doesn't. A translator working from a spreadsheet of keys and values has to guess, and a wrong guess looks like a bad translation even though it was really a missing piece of information.

Multiply that by a few thousand strings and you get a UI where every individual string is defensible and the product as a whole feels foreign. Japanese customers notice. They may not file a ticket about it, but it shapes whether your product looks like something built for them or something converted for them.

Where Japanese UI breaks

When I review a product's string handling ahead of a Japanese launch, the same patterns show up again and again:

• Concatenated sentences. Code like "Delete " + fileName + "?" assumes English word order. Japanese puts the object first and the verb at the end, so the natural phrasing is closer to {fileName}を削除しますか？. If the code builds the sentence from pieces, no translation of those pieces will ever read correctly.
• Reused strings. A developer sees that Open already exists and reuses the key in a new context. The English still works. The Japanese is now wrong in one of the two places.
• No context for ambiguous words. Short labels such as Archive, Post, Clear, or Free can each translate several ways. Without a note, the translator picks one.
• Hard-coded layouts. Buttons and table headers sized for English text clip or wrap badly when the Japanese string has a different shape. Japanese doesn't separate words with spaces, so wrapping in the wrong place can split a word in a way that reads as an error.
• Strings that never reach the translator. Text built in code, pulled from a database, or embedded in images stays in English, leaving a Japanese screen with an English sentence in the middle.
• UI and docs that disagree. If the UI strings and the help center are translated by different people at different times, the same feature ends up with two Japanese names. Customers following your documentation can't find the button it describes.

None of these are translation problems. They're engineering decisions that make good translation impossible.

Give translators context, in the file

The cheapest fix is also the most neglected: write notes for the translator next to the string. Most resource formats give you a way to attach a comment to a string. GNU gettext, for example, extracts comments placed immediately before a translatable string into the template file when you run xgettext with the --add-comments option (the common convention is --add-comments=TRANSLATORS:), so the note travels with the string to whoever translates it.

A useful note answers three questions: where the string appears, what part of speech it is, and what any placeholder will contain.

/* TRANSLATORS: Button label. Verb: opens the selected file. */
_("Open")

/* TRANSLATORS: Confirmation dialog title. %s is the name of a
   document the user created, e.g. "Q3 report.xlsx". */
printf(_("Delete %s?"), file_name);

Pair those notes with screenshots of each screen, and give the translator a running build if you can. A translator who can see the button will rarely translate it wrong.

Fix the code before you fix the Japanese

Context helps, but some problems have to be fixed by engineers. A few rules prevent most of them:

1. One complete message per string. Never assemble a sentence from fragments. Use a message format with named placeholders, such as ICU MessageFormat, so the translator controls word order.
2. One key per meaning. If the same English word appears in two contexts, give it two keys, even if the values are identical today.
3. Let layouts flex. Avoid fixed widths for text-bearing elements, and test with the longest real string, not the English one.
4. Externalize everything a user can read. That includes validation messages from the server, email templates, and text in images.

You can find many of these problems before a translator ever sees the files. Pseudo-localization replaces your English strings with altered versions so you can spot breakage in your own language. Android, for example, includes an English (XA) pseudolocale that adds accents, expands the text, and wraps each message unit in brackets. You enable it with pseudoLocalesEnabled in a debug build. Any sentence that shows up as two bracketed pieces is a concatenation bug. Any English that shows up without accents was never externalized.

A quick audit you can run this week

You don't need to read Japanese to see where your product is at risk:

• Search your codebase for string concatenation near user-facing text. Every + or template literal that joins a translated string with another translated string is a likely bug.
• Count your translator comments. Open your main resource file and see what share of strings have any note at all. Don't be surprised if the answer is almost none.
• List your single-word strings. Flag the ones that could be a verb or a noun, and check whether any are reused across screens.
• Turn on a pseudolocale and click through your five most-used screens. Screenshot every clipped label and every unaccented English string.
• Compare UI labels against your docs. Pull the Japanese labels for your top ten features from the resource files and search the Japanese documentation for each one. Every miss is a place where a customer following your docs gets lost.

If you've already shipped Japanese and want to know how good it really is, I wrote earlier about how to evaluate Japanese documentation you can't read. The same sampling approach works for the UI.

Why this takes someone who reads code and Japanese

This work sits in the gap between two teams. Your engineers understand the code but can't judge the Japanese. Your vendor understands Japanese but never sees the code. Each assumes the other has it covered.

At Inkwright, we work on both sides of that gap. I've spent decades writing software, so I can read your string handling, find where sentences are being built at runtime, and write the translator notes your developers never had time for. Hiromi, my co-founder, is a native Japanese speaker who has also worked as a software engineer, and she writes or reviews every Japanese deliverable we produce. Together we can make sure the Japanese in your product and the Japanese in your documentation describe the same thing.

Building a Japanese product, not a translated one

If Japanese customers keep sending screenshots of strings that don't make sense, the fix probably starts in your codebase, not your vendor's spreadsheet. I'd be glad to look at how your product handles strings and tell you where the Japanese is likely to break before your customers find it. You can reach me through the contact page.