Your Japanese Docs Are Translated, but Your API Still Expects John Smith

Your Japanese partner signed, their engineers started the integration, and two weeks later the tickets start arriving from Tokyo. A customer record fails validation. A name field rejects a perfectly ordinary name. An address comes back from your API in an order nobody in Japan would write it. A CSV export opens as gibberish. Each ticket gets answered, eventually, by one of your engineers who has to stop what they're doing to explain something the documentation should have said.

The frustrating part is that you paid for Japanese documentation, and it's fine. Every sentence was translated. But the parts developers actually rely on (the sample requests, field definitions, validation rules, and test data) still describe an American customer named John Smith who lives on Main Street. The prose was localized. The data contract wasn't.

Translation localizes sentences, not assumptions

A translator works on text. They will render "The name field accepts up to 50 characters" into flawless Japanese. They won't ask whether "characters" means characters or bytes, whether your API expects the family name first, or what happens when someone types their name in full-width katakana. Those aren't language questions. They're engineering questions that only surface in another language, and nobody on a typical localization project is assigned to ask them.

So the Japanese docs inherit every assumption baked into the English: Western name fields, Western address order, limits sized for ASCII, and examples that never exercise any of it. A Japanese developer follows the docs exactly, sends real data, and discovers the edges on their own.

Where the assumptions hide

When I look at API documentation that Japanese developers are struggling with, the same gaps tend to show up:

• Length limits that don't say what they count. In UTF-8, ASCII characters take one byte each, while most Japanese characters take three (RFC 3629 defines the byte ranges). If a field is sized in bytes and the docs say "50 characters," a Japanese user hits the limit at about a third of what the docs promise.
• Names. Japanese names are conventionally written family name first, and Japanese business forms commonly ask for a phonetic reading in kana alongside the kanji, because the kanji alone don't tell you how a name is pronounced or sorted. If your schema has first_name and last_name and no guidance, every integrator guesses at the mapping, and they don't all guess the same way.
• Addresses. Addresses written in Japanese script run from the largest area to the smallest, and postal codes are seven digits with a hyphen after the third, such as 112-0001, according to Japan's addressing guidance published by the Universal Postal Union. A schema built around street, city, state, and zip needs an explicit, documented mapping, not one each integrator invents.
• Full-width and half-width forms. Japanese input methods can produce full-width Latin letters and digits (ＡＣＭＥ１２３) and half-width katakana (ﾔﾏﾀﾞ). Does your API normalize them, reject them, or store them as typed? If the docs don't say, a duplicate-account check or a search filter will fail in ways that look random from the outside.
• Encoding of anything that leaves the API. CSV exports, webhook payloads, generated files. If the encoding isn't documented, the first person to discover it is a customer opening the file in the tool they use every day.
• Examples. If every sample payload contains only ASCII data, none of the above ever gets exercised, in your docs or in your own testing.

Decide the behavior, then document it

Most of these gaps aren't documentation problems first. They're undecided product behavior that the documentation exposes. Before anyone writes a word, get engineering to answer four questions for every field that holds human-entered text:

1. What does the length limit count: bytes, code points, or something else?
2. Is input normalized before it's stored or compared, and if so, with which normalization form?
3. Which name and address structures are supported, and how should a Japanese record map onto them?
4. What encoding does every export and outbound payload use?

Normalization shows why this has to be a deliberate decision. Unicode's NFKC form folds width variants together, which is often what you want for matching:

import unicodedata

unicodedata.normalize("NFKC", "ＡＣＭＥ１２３")  # 'ACME123'
unicodedata.normalize("NFKC", "ﾔﾏﾀﾞ")          # 'ヤマダ'

But the Unicode standard itself (UAX #15) warns that compatibility normalization must not be blindly applied to arbitrary text, because it can remove distinctions that matter. Whether you normalize on input, only when comparing, or not at all is a product decision. Once it's made, it's one sentence in the field reference, and that sentence saves every integrator an afternoon.

Put Japanese data in your examples

Then fix the examples, in both languages. Add at least one complete request and response that uses realistic Japanese data. If your schema supports it, something like this:

{
  "family_name": "山田",
  "given_name": "太郎",
  "family_name_kana": "ヤマダ",
  "given_name_kana": "タロウ",
  "postal_code": "112-0001",
  "prefecture": "東京都"
}

One good example does three jobs. It shows Japanese integrators exactly how their data maps onto your schema. It gives your own QA team a ready-made test case. And it tells a Japanese technical evaluator, without anyone saying it out loud, that you thought about their market before they had to ask.

Pair the examples with validation errors that say which rule failed and in what unit. "Name exceeds 50 bytes" is something a developer can act on; "Invalid name" sends them to your support queue. I wrote about turning error responses into documentation in Your API's Error Messages Are the Documentation Developers Actually Read, and Japanese input is where vague errors cost the most.

A quick audit you can run this week

You don't need to hire anyone to find out how exposed you are:

• Search your support tickets from Japanese customers and partners for validation failures, character problems, and address or name complaints.
• List every text field in your API reference and check whether its length limit names a unit.
• Send one realistic Japanese record through your own sandbox, including a full-width string, and compare what comes back with what the docs say should happen.

If any of those turn up surprises, your Japanese developers have already found them.

Why this takes an engineer who reads Japanese

A translator can't fix this, and neither can a technical writer who only works in English. It means reading the schema, the validation code, and sometimes the database migrations to learn what the system actually does, then writing it down in English and in Japanese that a developer in Tokyo recognizes as written for them.

Documenting the API your Japanese customers actually use

If your support queue keeps collecting tickets from Japanese integrators about rejected names, mangled addresses, or garbled exports, the fix is probably in your data contract and its documentation, not your translation. I'd be glad to walk through your API reference with you and point out where it assumes an English-speaking customer. You can reach me through the contact page.