Writing localization bug reports someone can actually act on

Localization bugs have a shape that regular bugs mostly do not: the person who notices the problem often cannot read the source text, and the person who can fix it often cannot read the report written about it in the target language. That gap is exactly why the report has to do more work than a typical bug report — it cannot rely on both sides sharing the same frame of reference.

A report that says the Japanese feels off is a true statement and a useless one. It tells the fixer that something is wrong without telling them what, where, or against what standard. Every report like this either gets ignored or costs someone a round of back-and-forth just to find out what was actually meant — time that a slightly more complete report from the start would have saved entirely.

What an actionable report contains

An actionable localization bug report answers the same six questions every time, regardless of what kind of problem it is: what string, what it currently says, what it should say instead, why, where the reporter saw it, and on what build. Missing any one of these turns the report into a request for more information before anyone can act.

• String key or ID — the only reliable way to find the exact line among thousands of near-identical ones
• Source text — what the original says, so the fixer can judge accuracy, not just fluency
• Current target text — the actual string as it ships, copied verbatim, not paraphrased from memory
• Expected vs. actual — what is wrong (mistranslation, wrong tone, truncation, wrong placeholder) stated as a concrete difference, not an impression
• Screenshot — shows truncation, overlap, and font issues that text alone cannot describe
• Build and language — which build the reporter tested and which language variant, since a fix in one language build says nothing about another

A minimal template

A short structured template beats a free-text field, because it forces the reporter to fill in what they might otherwise skip. It does not need to be elaborate:

Key: dialogue.quest_042.line_03
Source (EN): "You've got nerve, showing up here."
Current (JA): それは度胸がありますね、ここに来るとは。
Expected: sarcastic/threatening tone, not polite praise
Build: 1.4.2-rc3
Language: ja-JP
Screenshot: attached

Why vague reports go nowhere

「Feels off」, 「sounds weird」, and 「doesn't sound natural」 describe a reaction, not a defect. A translator reading one of these has to reconstruct the entire context the reporter had in their head: which line, what specifically triggered the reaction, and what a better version would look like. Most of the time that reconstruction never happens — the report sits open, or gets closed as unreproducible, and the actual problem ships.

This is not a discipline problem on the reporter's side; it is usually that they genuinely do not know which of the six items above matters, because nobody told them. A short template fixes this by asking for the specifics instead of hoping someone remembers to include them.

Fix the file, not just the build

A localization bug is only closed when the source-of-truth file is corrected — the spreadsheet, the CMS entry, the translation memory, whatever the pipeline treats as canonical. A patch applied directly to a build asset (an override file, a manual string edit in a build config) closes the symptom but not the cause.

The next time text is exported from the canonical source — for a new build, a new platform, or a routine content update — the old, wrong string comes back, because nothing told the source of truth it was wrong. Anyone who has re-triaged the same localization bug twice has usually hit exactly this: the fix lived in the wrong place.