Your Japanese Docs Are Published, but Your Search Box Can't Read Them

You paid to localize your documentation. The Japanese pages are live, the vendor's invoice is closed, and the language switcher works. Yet your Japanese customers keep opening support tickets about things the docs already answer. When your support team replies with a link, the customer writes back something polite that amounts to: "I searched for this and couldn't find it."

They're telling the truth. In a lot of the documentation sites I review, **the Japanese content exists, but the search, navigation, and linking around it were built for English.**The translation was paid for and finished, but it still isn't doing its job because nobody can reach it.

Search engines that expect spaces

Most search tools start by splitting text into words. In English, that's easy: words are separated by spaces. Japanese doesn't put spaces between words. A sentence like APIキーを再発行する方法 is a single unbroken run of characters, and a search index that splits on whitespace treats much of it as one giant token.

The result is a search box that only matches when the customer happens to type the exact string that appears on the page, or one that fails in ways nobody on your English-speaking team will ever notice, because your team never searches in Japanese.

The fix is word segmentation, and whether you have it depends on your search tool and how it's configured:

• Algolia segments Japanese at both query time and indexing time, but only when you set both queryLanguages and indexLanguages to ja. Its documentation is explicit that both settings are needed for segmentation to apply. It also indexes Japanese words in hiragana alongside their original form, which helps customers who are still typing before converting to kanji.
• Lunr, which sits behind many static documentation sites, needs the separate lunr-languages package before it can segment Japanese.
• Homegrown search built on a database LIKE query or a simple tokenizer usually has no Japanese handling whatsoever.

None of these tools are bad. They just don't do the right thing for Japanese by default, and the default is what most docs sites ship with.

The same word, spelled three ways

Even with segmentation in place, Japanese search has a second problem: the same term can be written several ways. A customer might type ユーザ while your docs say ユーザー. They might type full-width ＡＰＩ from their input method while your pages use half-width API. Older systems and some copy-pasted text still produce half-width katakana like ｱｶｳﾝﾄ.

Some of this can be fixed mechanically. Unicode's NFKC normalization converts full-width Latin letters to half-width and half-width katakana to full-width, so ＡＰＩキー becomes APIキー and ｱｶｳﾝﾄ becomes アカウント. Apply the same normalization to the index and to every query, and a whole class of misses disappears.

What normalization won't fix is the long-vowel mark. ユーザ and ユーザー are both valid, normalized text; they're just different spelling conventions. Those need to be handled as synonyms in your search configuration, and the synonym list should come straight from your Japanese term base, so that search knows about every variant your writers decided not to use. If you don't have a term base yet, that's the real problem. I wrote about why Japanese docs fall behind without one.

Navigation that leads back to English

Search is the most visible failure, but it isn't the only one. A few others show up again and again:

• The language switcher dumps people on the homepage. A Japanese customer lands on an English page from a Google result, clicks 日本語, and is sent to the Japanese home page instead of the same page in Japanese. Many won't bother searching again.
• Cross-references point to English. Translators translate the link text, but the URL underneath still points to the English page. The customer clicks a Japanese link and lands in English halfway through a task.
• Search engines can't connect your language versions. Google uses hreflang annotations to understand which pages are localized versions of each other, and its documentation is strict about how they work: each version must list itself and every other version, and if two pages don't point to each other, the annotations are ignored. A localization pass that adds Japanese pages without updating the English ones often breaks this silently. Google also says it doesn't use hreflang or the HTML lang attribute to detect a page's language, so you can't rely on markup to make up for content that's mixed or mislabeled.
• Headings generate unusable anchors. Some static site generators build anchor IDs from heading text and strip characters they don't recognize. Japanese headings can end up with empty or numbered anchors, so a support engineer can't link a customer to the exact section that answers their question.

A findability audit you can run this week

You don't need to read Japanese to test most of this. Ask a Japanese-speaking colleague, partner, or customer success rep for an hour, or do it yourself with a list of terms:

1. Pull ten real questions from Japanese support tickets and write down the key term from each, in Japanese.
2. Search for each term in your Japanese docs search, then search again with variants: full-width and half-width letters, with and without the long-vowel mark, and in hiragana. Note which searches return nothing even though the page exists.
3. Click the language switcher on five deep pages. Does it keep you on the same page, or send you home?
4. Check the links on your three most-visited Japanese pages. Count how many lead to English pages.
5. Inspect hreflang on one page in each language. Confirm every version lists itself and its counterparts.
6. Copy a section link from a Japanese page and open it in a new tab. Does it take you to the right heading?

Every failure on that list is a support ticket you're already paying for, from a customer who did the right thing and looked first.

Why this needs both an engineer and a Japanese writer

This problem falls between teams. Your translation vendor delivers text and never sees your search configuration. Your docs engineers own the search configuration and can't tell whether a Japanese query should have matched. Each assumes the other has it covered.

At Inkwright, we work on both sides. I've spent decades writing software, so I can read your search configuration, your static site generator's templates, and your link structure, and tell you where Japanese content is getting lost. Hiromi, my co-founder, is a native Japanese speaker and a software engineer who writes or reviews every Japanese deliverable we produce, including the term base and synonym lists that make search work.

Making the investment reachable

If your Japanese customers are asking questions your Japanese docs already answer, the translation may be fine. The problem is that they can't find it. I'd be glad to review your Japanese documentation the way a Japanese customer would and show you where it breaks down. You can reach me through the contact page.