国際化（i18n）開発ガイド（MuseScore 4.x / レガシー QML）

本ドキュメントでは、MuseScore プラグインの 文言を多言語化し、翻訳ファイルを用意してプラグインへ組み込むまでの流れを、ツールの導入から操作・配布・4.x 特有の注意まで順に説明します。

対象: MuseScore Studio 4.x のレガシー QML プラグイン。
文字列は qsTr / qsTranslate でマークし、独自訳は translations/locale_XX.qm に置くのが基本です。4.x における独自 .qm の扱いについては §8 を参照してください。

1. 全体の流れ

mermaid

flowchart TD
    A[方針決定 A/B/併用] --> B[QML を qsTr / qsTranslate 化]
    B --> C[Qt Linguist 系ツール導入]
    C --> D[lupdate で .ts 生成]
    D --> E[Linguist で翻訳]
    E --> F[lrelease で .qm 生成]
    F --> G[translations/ へ配置]
    G --> H[MuseScore の言語を切替えて確認]

段階	やること
1	本体訳の再利用か、独自翻訳か（または併用）を決める
2	UI／メッセージの文字列を `qsTr` / `qsTranslate` で囲む
3	`lupdate` / Qt Linguist / `lrelease` を使えるようにする
4	`translations/locale_XX.ts` を作り、翻訳して `.qm` にする
5	プラグインサブフォルダに同梱し、MuseScore で確認する

2. 方針の選び方

方針	手段	向く場合	4.x での確実性
A. 本体翻訳の再利用	`qsTranslate("コンテキスト", "原文")`	音名、Apply/Cancel、既存メニュー語	高い（本体の言語ファイルを使う）
B. プラグイン独自翻訳	`qsTr` ＋ `translations/locale_XX.qm`	プラグイン固有の説明・ラベル	4.x では制限あり（§8）
C. 併用	A を優先し、足りない語だけ B	ほとんどの実用プラグイン	A で土台を固め、B を足す
D. プラグイン内辞書	QML 内のマップ	B が反映されない場合の代替	実装次第で確実

同梱例:

note_names … 音名に qsTranslate("global", …)
lilyrics / tuning … UI に qsTr、ボタンに qsTranslate("PrefsDialogBase", …)

3. 使用できるツール

ツール	役割
Qt Linguist	`.ts` を開いて翻訳を入力・保存する GUI
`lupdate`	`.qml`（等）から翻訳対象文字列を抽出し `.ts` を生成／更新
`lrelease`	`.ts` → 実行用 `.qm` にコンパイル
VSCode / Cursor	ソースの `qsTr` 化、フォルダ管理
MuseScore 4.x	Preferences の言語切替で実行確認

補助:

もの	用途
Transifex 上の MuseScore / ソース検索	`qsTranslate` 用のコンテキスト名調べ
スプレッドシート	翻訳者との受け渡し（最終的には `.ts` に戻す）

4. ツールのインストール

4.1 手軽な方法: Linguist 単体（Windows）

翻訳作業だけなら、SDK 全体は不要です。

Qt の Linguist 配布を入手する: https://download.qt.io/linguist_releases/
インストーラを実行する
Qt Linguist が起動することを確認する

lupdate / lrelease は Linguist 単体に含まれない／パスが通らないことがあります。その場合は次の「Qt 導入」か、Linguist の File → Release で .qm を出す運用にします。

4.2 本格的な方法: Qt Online Installer

Qt の入手ページから Qt Online Installer を取得する（アカウントが必要な場合あり）
インストール時、開発用に Qt 6.x を選び、Qt Linguist およびコマンドラインツールが含まれる構成にする

典型的な配置例（バージョンは環境による）:

C:\Qt\6.x.x\msvc20xx_64\bin\lupdate.exe
C:\Qt\6.x.x\msvc20xx_64\bin\lrelease.exe
C:\Qt\6.x.x\msvc20xx_64\bin\linguist.exe

PowerShell でパスを通す例:

powershell

$env:Path = "C:\Qt\6.8.0\msvc2022_64\bin;" + $env:Path
lupdate -version
lrelease -version

4.3 macOS / Linux

macOS: Online Installer、または Homebrew 等で Qt を導入し bin を PATH へ
Linux: ディストリの qttools5-dev-tools / Qt6 相当パッケージ、または Online Installer

which lupdate / lupdate -version で確認します。

5. コード側の書き方（プラグイン実装）

5.1 基本: `qsTr`

qml

StyledTextLabel {
    text: qsTr("Apply lyrics in lilypond format.")
}

FlatButton {
    text: qsTr("Run")
    // 翻訳者向けコメント（第 2 引数）
    // qsTr("Run", "verb: execute the plugin")
}

プレースホルダ・複数形:

qml

qsTr("Pages: %1").arg(pageCount)
qsTr("%n note(s) selected", "", noteCount)

5.2 本体訳の再利用: `qsTranslate`

qml

// 音名など
qsTranslate("global", "C♯")

// ダイアログ定番ボタン（同梱プラグインと同様）
qsTranslate("PrefsDialogBase", "Apply")
qsTranslate("PrefsDialogBase", "Cancel")

コンテキスト（第 1 引数）は MuseScore 本体の翻訳ファイルに存在する名前です。
不明なときはソースや Transifex で原文を検索し、使われているコンテキストを調べます。

5.3 メニューパス

qml

// 先頭の "Plugins" は翻訳しない（ドキュメント推奨）
menuPath: "Plugins." + qsTr("Note Names")

4.x では title / categoryCode も重要なので、表示名は title: qsTr("…") も検討します。

5.4 やってはいけないこと

NG	理由
UI 文字列を普通の `"..."` のまま残す	抽出も翻訳もされない
動的に連結した文だけを `qsTr` する	抽出・文法が壊れやすい。文全体を `qsTr` し `%1` を使う
全プラグインを Plugins 直下にバラ置き	翻訳衝突の原因。サブフォルダ必須に近い

6. 翻訳ファイルの作成操作

本体の翻訳コンテキスト名の一覧は本体翻訳コンテキスト一覧を参照してください。

lupdate / lrelease の手動手順に加え、本リポジトリの tools/i18n/compile-translations.py で一括実行できます。GitHub Release 時の自動コンパイルは tools/i18n/README.md と .github/workflows/compile-plugin-translations.yml を参照してください。

6.1 推奨ディレクトリ

myplugin/
  myplugin.qml
  extra.js                 # あれば
  translations/
    locale_ja.ts
    locale_ja.qm
    locale_de.ts
    locale_de.qm

言語コード XX の例: ja（日本語）、de（ドイツ語）、fr、zh_CN など。
MuseScore の UI 言語と合わせます。

6.2 `lupdate` で `.ts` を生成・更新

プラグインフォルダで:

powershell

cd $env:USERPROFILE\Documents\MuseScore4\Plugins\myplugin

# 初回・更新（日本語）
lupdate myplugin.qml -ts translations/locale_ja.ts

# 複数ソースがある場合
lupdate myplugin.qml helpers.js -ts translations/locale_ja.ts

# ドイツ語も並行して管理
lupdate myplugin.qml -ts translations/locale_de.ts

既存の .ts がある場合、未翻訳の新規文字列が追加され、既訳は可能な限り残ります。
QML を直したら、翻訳前に毎回 lupdate を回す習慣にします。

6.3 Qt Linguist での翻訳操作

Qt Linguist を起動する
File → Open で translations/locale_ja.ts を開く
左（または上）の一覧から未翻訳（？／白紙アイコン）を選ぶ
下部の翻訳欄に訳文を入力する
訳が確定したら、項目を 翻訳済み／完了 にする（チェック／Done。バージョンで UI が多少異なる）
File → Save で .ts を保存する

ヒント:

同一英文でも文脈が違う場合は、qsTr の第 2 引数コメントを活用する
長文は UI の折り返しを考え、ボタンは短く保つ

6.4 `.qm` の生成（`lrelease` または Linguist）

コマンド:

powershell

lrelease translations/locale_ja.ts
# → translations/locale_ja.qm が生成・更新される

Linguist から:

locale_ja.ts を開いた状態で File → Release…（または Release）
locale_ja.qm の保存先を translations/ にする

配布・実行に必要なのは主に .qm です。.ts は翻訳メンテ用なのでリポジトリには両方置くのが望ましいです。

6.5 MuseScore 側での確認

MuseScore → Preferences → General（または Language） で UI 言語を変更する
必要なら MuseScore を再起動する
プラグインを実行し、ラベル・ダイアログ・メニューが訳されているか確認する
言語を戻し、原文（多くは英語）に戻ることも確認する

7. プラグインへの組み込みチェックリスト

#	項目
1	ユーザー向け文字列が `qsTr` / `qsTranslate` になっている
2	プラグインが専用サブフォルダにある
3	`translations/locale_XX.qm` が存在する
4	zip 配布に `translations/` が含まれている
5	対象言語の MuseScore で表示確認した
6	Apply/Cancel など可能なら `qsTranslate` で本体訳を使っている

8. MuseScore 4.x での注意（重要）

3.x 向けドキュメント（i18n.md）では、translations/locale_XX.qm を置けばプラグイン実行時に読まれると説明されています。
Plugins for 4.x でも、翻訳ファイルをプラグインサブフォルダの translations に置く構成が案内されています。

一方、MuseScore 4.x ではプラグイン固有の .qm が常に読み込まれるとは限らず、独自訳が反映されないことがあります（関連: GitHub Issue #30833 — Support translations of custom plugins）。

8.1 推奨する実装方針

まず qsTranslate で本体にある語を最大限再利用する
独自文言も qsTr 化し、.ts / .qm は 手順どおり同梱する（標準的な構成の維持、および環境差への備え）
独自訳が反映されない場合は、次の 代替実装（プラグイン内辞書） を使う

8.2 代替実装: プラグイン内辞書

qml

property string uiLang: {
    var n = Qt.locale().name  // 例: "ja_JP"
    if (n.indexOf("ja") === 0)
        return "ja"
    return "en"
}

readonly property var trMap: ({
    "ja": {
        "intro": "オプションを選んで Apply を押してください。",
        "run": "実行"
    },
    "en": {
        "intro": "Choose options and press Apply.",
        "run": "Run"
    }
})

function t(key) {
    var table = trMap[uiLang] || trMap["en"]
    return table[key] || trMap["en"][key] || key
}

// 使用例
// StyledTextLabel { text: t("intro") }

qsTr を先に試し、原文のまま返ってきたときだけ辞書へフォールバックする形もあります。

qml

function tr(english) {
    var s = qsTr(english)
    if (s !== english)
        return s
    if (uiLang === "ja" && jaMap[english])
        return jaMap[english]
    return english
}

小規模プラグイン向きです。
文言が増えたら、辞書を別 .js / .qml に分離してもよいです。
補助 .qml に分割する場合、ファイル内に MuseScore という語を書くと 別プラグインとして検出されることがあります（開発ノウハウ §7.3）。アプリ名が必要な文言は "Mu" + "seScore" のように実行時組み立てにしてください。
qsTr とプラグイン内辞書を混在させる場合は、役割を分けて保守しやすくしてください（例: 本体再利用は qsTranslate、独自文言は t() / tr()）。

完成例（i18n.js ＋ソース分割＋ musescore-plugin-lib）はプラグインテンプレートからダウンロードできます。実例: KalimbaNotation の I18n.qml。

9. よくある失敗

症状	原因の例
`.ts` に文字列が出ない	`qsTr` していない／`lupdate` の入力ファイル漏れ
Linguist で訳したのに実行時英語のまま	`.qm` 未生成、置き場所違い、4.x で独自 `.qm` が反映されない制限（§8）
一部だけ訳される	本体 `qsTranslate` 分だけ効いている（独自 `.qm` 未反映の典型）
プラグインが一覧に出ない	import／Qt 6 非互換（i18n 以前の問題。ノウハウ §6）
訳が他プラグインと混ざる	Plugins 直下に複数 `.qml` を並べている
補助 `.qml` が Plugins 一覧に出る	子ファイル内に `MuseScore` という語がある（ノウハウ §7.3）

10. 参考

内容	参照
MuseScore 旧 i18n 解説	`docs/old_docs/i18n.md`
PluginAPI Docs	i18n.html
本体コンテキスト一覧	本体翻訳コンテキスト一覧
翻訳コンパイル自動化	翻訳コンパイル自動化
Qt Quick i18n	https://doc.qt.io/qt-6/qtquick-internationalization.html
Qt Linguist	https://doc.qt.io/qt-6/linguist-translators.html
lupdate	https://doc.qt.io/qt-6/linguist-lupdate.html
Linguist 単体 DL	https://download.qt.io/linguist_releases/
4.x 配置案内	https://musescore.org/en/node/337468
独自 `.qm` が反映されない場合	https://github.com/musescore/MuseScore/issues/30833
分割＋lib＋日本語の雛形	プラグインテンプレート
開発ノウハウ要約	開発ノウハウ

国際化（i18n）開発ガイド（MuseScore 4.x / レガシー QML） ​

1. 全体の流れ ​

2. 方針の選び方 ​

3. 使用できるツール ​

4. ツールのインストール ​

4.1 手軽な方法: Linguist 単体（Windows） ​

4.2 本格的な方法: Qt Online Installer ​

4.3 macOS / Linux ​

5. コード側の書き方（プラグイン実装） ​

5.1 基本: qsTr ​

5.2 本体訳の再利用: qsTranslate ​

5.3 メニューパス ​

5.4 やってはいけないこと ​

6. 翻訳ファイルの作成操作 ​

6.1 推奨ディレクトリ ​

6.2 lupdate で .ts を生成・更新 ​

6.3 Qt Linguist での翻訳操作 ​

6.4 .qm の生成（lrelease または Linguist） ​

6.5 MuseScore 側での確認 ​

7. プラグインへの組み込みチェックリスト ​

8. MuseScore 4.x での注意（重要） ​

8.1 推奨する実装方針 ​

8.2 代替実装: プラグイン内辞書 ​

9. よくある失敗 ​

10. 参考 ​

国際化（i18n）開発ガイド（MuseScore 4.x / レガシー QML）

1. 全体の流れ

2. 方針の選び方

3. 使用できるツール

4. ツールのインストール

4.1 手軽な方法: Linguist 単体（Windows）

4.2 本格的な方法: Qt Online Installer

4.3 macOS / Linux

5. コード側の書き方（プラグイン実装）

5.1 基本: `qsTr`

5.2 本体訳の再利用: `qsTranslate`

5.3 メニューパス

5.4 やってはいけないこと

6. 翻訳ファイルの作成操作

6.1 推奨ディレクトリ

6.2 `lupdate` で `.ts` を生成・更新

6.3 Qt Linguist での翻訳操作

6.4 `.qm` の生成（`lrelease` または Linguist）

6.5 MuseScore 側での確認

7. プラグインへの組み込みチェックリスト

8. MuseScore 4.x での注意（重要）

8.1 推奨する実装方針

8.2 代替実装: プラグイン内辞書

9. よくある失敗

10. 参考