japanese
Principles
Do not turn an English-constructed sentence into a word-for-word Japanese replacement. Decide what you want to convey first, then write it in the way Japanese speakers normally express that idea.
Literal translations can feel unnatural because English metaphors and phrasal verbs do not necessarily retain their meaning when mapped directly onto Japanese verbs. 「寄せる」, for example, does not mean bringing in a PR, and 「確実にする」 does not refer to the act of checking. The reader must reconstruct the intended meaning from the literal wording, which makes the text more effortful to read.
Use the following process for expressions that are not listed in the table below.
- Mentally reconstruct the English source of the sentence you wrote. If each English word or phrasal verb has been replaced one by one with a Japanese equivalent, suspect a literal translation.
- Imagine whether a Japanese speaker would say the sentence as-is at work or in daily life. If not, rewrite it.
- Check whether the verb is being used metaphorically. If verbs that describe bodily actions, such as , , , or , are used for abstract work, replace them with verbs that describe the actual task.
- Add a predicate if one is missing.
- If the same ending appears three or more times in a row, vary the sentence structure.
The conversion table is a checklist for catching common literal translations before they slip through. Use the process above to judge an expression, whether or not it appears in the table.
Symbols
Do not use round parentheses, colons, dashes, or slashes as separators in body text. These punctuation marks make readers move back and forth between the main text and supplementary information, which reduces readability.
If you want to put a note in parentheses, turn it into an independent sentence or remove it if it is unnecessary. If you want to list alternatives separated by slashes, connect them with 「か」 or 「または」, or choose one. Do not put a colon after an item name or heading to make it look like a label. Write a complete sentence with a predicate instead.
Code, commands, paths, and commit-message formatting are exempt from this rule.
Noun-Final Sentences
Do not end body text, descriptions, or conversational sentences with a noun. Add a predicate.
Headings, labels, UI status messages, and very short bullet points may end with a noun.
Sentence Endings and Requests
The ending 「〜どうぞ」 is used when recommending something to another person or offering something to them. Do not use it for requests. Use 「〜ください」 or 「〜をお願いします」 instead.
The ending 「〜まで」 takes a predicate after it. Do not end a sentence with 「〜まで」 alone; add a predicate.
Literal Translations of Technical Jargon
Do not translate English phrasal verbs and metaphors literally. State what will actually be done.
- Do not translate as or . Write , , or .
- Do not translate as or . Write , , or .
- Do not translate or as . Write , , or .
- Do not translate or as . Write or .
- Translate as or .
- Do not translate as . Write .
- Do not translate as . Write or .
- Do not translate as . Write or .
- Translate as or .
- Translate as or .
- Translate as or .
- Translate as or .
- Translate as or .
- Translate as or .
- Translate as or .
- Do not translate as . Write or .
- Do not translate as . Write or , or go straight to the main point.
- If translating as sounds unnatural, write .
The 「〜きる」 pattern often results from a literal translation of
or
. To convey that something was completed from start to finish, use forms such as
,
, or
.
Verbose Structures
Shorten an expression whenever doing so does not change its meaning.
- →
- →
- →
- → . If the work will continue, write .
- → . You may use when it is an established business term.
- →
Remove the 「〜の方」 form only when it does not indicate direction or comparison. Keep 「方」 where it is needed, as in 「こちらの方が速い」 or 「東京の方へ向かう」. Remove it when it is used only to obscure the referent, as in 「資料の方をお送りします」.
Do not rewrite natural, idiomatic expressions such as 「問題なく動作します」 or 「ご不明点がございましたら」. Only check whether they suit the reader and context.
Katakana
Katakana itself is not a problem. If a term is sufficiently clear to Japanese readers, use the native Japanese word.
Keep established terms such as
and
as they are.
Tone
Use polite
style for explanations and reports to users. Keep them concise, but still give them a predicate. Use
style in technical documentation as well; only headings may end with a noun.
Write commit messages in plain form (
) and end them with a verb that describes the action.
UI buttons and labels may be short. Use a clear action noun such as
or
, or a verb form such as
. Keep the style consistent throughout a single screen.
Do not mix polite and plain forms. Remove any mixing, even if it appears intentional.
Examples
Work report.
バグの修正。テストの実行。問題なし。
→ バグを修正し、テストを実行しました。問題はありませんでした。
Next step.
次は PR のマージまで。
→ 次は PR をマージします。
Request.
Commit message.
認証まわりの修正。
→ fix: 認証エラーのハンドリングを修正する
不要な依存関係を落とす
→ chore: 未使用の依存関係を削除する
PR description.
この PR では変更を寄せます。レビューどうぞ。
→ この PR で変更を取り込みます。レビューをお願いします。
既知の問題を倒す対応。
→ 既知の問題を解消しました。
UI copy.
エラー。再試行。
→ エラーが発生しました。再試行してください。
Sentence with many symbols.
設定ファイル（config.ts）を更新しました：タイムアウト値を変更／ログ出力を追加。
→ config.ts の設定を更新しました。タイムアウト値を変更し、ログ出力を追加しています。
Splitting a long sentence.
今回の変更では認証フローを更新し、トークンの検証ロジックを修正し、
エラーハンドリングを改善し、テストを追加することができます。
→ 今回の変更では、認証フローを更新し、トークン検証とエラーハンドリングを
修正しました。あわせてテストを追加しています。
Final Checks
- Does the body text end with a noun?
- Does any sentence end with 「〜どうぞ」 or 「〜まで。」?
- If you reconstruct the English source, does it look like each word was replaced one by one?
- Are verbs that describe bodily actions being used for abstract work?
- Do any parentheses, colons, dashes, or separating slashes remain in the body text?
- Is any sentence too long? If so, split it.
- Do polite and plain forms mix unintentionally?
- Does the same sentence ending repeat?