注文のライフサイクル

🌐 言語: 🇻🇳 Tiếng Việt · 🇬🇧 English · 🇯🇵 日本語（現在）

GP247 システムでの言語（多言語／i18n）の使い方

はじめに

このドキュメントでは、**GP247 の多言語システム（i18n）**の仕組みを説明します。翻訳文字列がどこに 保存されるか、システムがどの優先順位で表示言語を選ぶか、そしてパッケージをアップグレードしたときに 新しい言語を追加する方法、文言を1つずつ編集する方法、翻訳文字列を更新し直す方法を解説します。 GP247 サイトの開発者と管理者向けのドキュメントです。読み終えると仕組みを理解でき、サイトや管理画面に 表示される1行の文言を変えるには、どこを操作すればよいかが正確にわかります。

ℹ️ 用語メモ: locale（ロケール） ＝ vi、en のような短い言語コード。翻訳文字列（translation string） ＝「コード → 文言」の組（例: action.save → 保存）。管理画面（Admin） ＝ サイトの管理エリア。

1. 仕組み

GP247 は データベース優先（DB-first） のモデルを使います。2つの別々の概念があり、それぞれ DB の2つのテーブルに対応します。

テーブル 役割 内容の例
admin_language サイトにインストール済みの言語の一覧（有効／無効、並び順、旗、RTL） vi — Tiếng Việt · en — English
languages 実際の文言の保管場所（コード → テキスト、ロケールごと） action.save / ja → 保存

（実際のテーブル名には GP247_DB_PREFIX による接頭辞が付きます。既定は gp247_ です。例: gp247_languages。）

1.1. 翻訳文字列はどこにあるか？

  • 主な取得元は DB の languages テーブルです。 表示されるすべての文言はここから読み込まれます。
  • ディスク上の言語ファイルは予備にすぎません。 各パッケージには Lang/{en,vi}/ フォルダーがあり （例: vendor/gp247/core/src/Lang/）、Laravel に gp247:: 名前空間で登録されています。これらが 使われるのは、DB に対応するコードがない場合だけです。
  • languages テーブルの初期データは、各パッケージの seeder から入ります（言語ファイルからではありません）。 4 章 を参照してください。

languages テーブルのカラム:

code       // 翻訳文字列のコード。例: "action.save"        (location との組み合わせで一意)
text       // 翻訳済みの文言。例: "保存"
position   // グループ／エリア。例: "action", "store.admin" (管理画面での絞り込みに使用)
location   // ロケール。例: "en" または "vi"

admin_language テーブルのカラム: name（表示名）、code（ロケールコード、一意）、icon（旗）、 status（1 ＝ 有効）、rtl（1 ＝ 右から左のレイアウト）、sort（並び順）。

1.2. 文言が表示される流れ

コードや view では、ヘルパー関数 gp247_language_render() で文言を取得します。

gp247_language_render('action.save');            // -> "保存" (現在のロケールが ja の場合)
gp247_language_render('welcome', ['name' => 'An']); // 文字列内の :name を "An" に置き換えます

この関数は次の順序で動きます。

  1. gp247_get_locale()（Laravel の app()->getLocale() と同じ）で現在のロケールを判定します。
  2. そのロケールのすべての文字列を DB から取得します: Languages::getListAll($locale) → code => text のマップを返します。 結果は 1リクエストの範囲でキャッシュされます（同じページ読み込み中に何度も問い合わせません）。
  3. コードが DB にある場合 → その text を返します（:key 形式のパラメーターがあれば置き換えます）。
  4. ない場合 → 予備として Laravel の trans($string) を使います（ディスク上の言語ファイルを読みます）。

関連するヘルパー関数:

関数 用途
gp247_language_render($key, $replace, $locale) コードから文言を取得します（最もよく使います）
gp247_language_quickly($key, $default) 上と同じですが、既定値を指定できます
gp247_get_locale() 表示中のロケールを取得します
gp247_lang_switch($code) 現在の言語を切り替えます（有効性を確認し、session に保存）
gp247_language_all() 有効な言語の一覧を取得します（admin_language から）

⚠️ 技術的な注意: 言語関数を __construct や早い段階で動く middleware の中で呼ばないでください。 その時点ではロケールがまだ設定されていないことがあり、間違った言語で表示される原因になります。

2. 優先順位

区別すべき2つの優先順位の層があります。

2.1. 表示ロケールの選択の優先順位（このリクエストでどの言語が有効か）

middleware Localization（vendor/gp247/core/src/Middleware/Localization.php）が、 高いものから低いものへ次の順で決めます。

  1. session('locale') — ユーザーがすでに言語を選んでいる（session に残っている）場合 → 最優先です。
  2. gp247_store_info('language') — ストアに設定された既定の言語です。
  3. config('app.locale') — Laravel の既定ロケールです（.env / config/app.php）。
  4. 選ばれた値は、有効な言語の一覧（admin_language、status = 1）と照合し直されます。 有効でない場合は、sort の順で最初の有効な言語が使われます。

確定すると、middleware は app()->setLocale(...) を呼び、値を session に保存し直します。

URL の接頭辞（例: /vi/...）で言語を判定する仕組みはありません。ロケールは session ＋ ストアの既定言語で制御されます。ユーザーは画面上の言語切り替えボタン （gp247_lang_switch() を呼びます）で言語を変更し、新しい値は以降のリクエストのために session に保存されます。

2.2. 文言の取得元の優先順位（あるコードのテキストをどこから取るか）

同じコードの翻訳文字列について:

  1. DB のレコード（languages、location ＋ code が一致）— 最優先です。
  2. ディスク上の言語ファイル（trans() 経由）— DB にそのコードがない場合だけ使われます。

→ 重要な結論: 文言を変えたいときは、DB で（管理画面から）編集してください。 DB の内容は常に ファイルより優先されるためです。DB に対応するコードがすでにある場合、vendor/ 内の言語ファイルを編集しても通常は効果がありません。

3. 追加と編集の方法

作業は2種類あります。言語の追加・編集（admin_language の行）と、文言の追加・編集 （languages の行）です。どちらも管理画面で行います。

3.1. 新しい言語を追加する

  1. 管理画面にログインし、**「言語」**画面（パス /{admin_prefix}/language）を開きます。
  2. 新規追加ボタンをクリックし、次を入力します。
    • 「名前」（Name）— 表示名（例: 日本語）。
    • 「コード」（Code）— ロケールコード。小文字で、一意にします（例: ja）。
    • 「アイコン」（Icon）— 旗・アイコン（任意）。
    • RTL — 右から左に読む言語（例: アラビア語）の場合にオンにします。
    • 「並び順」（Sort）— 表示の順番。「ステータス」（Status）— 言語を有効にするにはオン（1）にします。
  3. 保存します。成功すると、新しい言語が一覧と、サイト上の言語切り替えボタンに表示されます。

この時点では、新しい言語には languages の文言がまだ1つもありません。手順 3.3 に進んで翻訳を入力してください。

3.2. 言語の編集・有効化／無効化・削除

  • 「言語」画面に戻り、該当する行の「編集」（Edit）を選んで、名前・旗・並び順を変更したり、Status を切り替えたりします。
  • 安全のための制約:
    • システムは有効な言語を常に1つ以上残します。すべてを無効にすることはできません。
    • 基本の2言語 vi と en は削除できません（定数 GP247_GUARD_LANGUAGE で保護されています）。

3.3. 文言（翻訳）の追加・編集

  1. **「言語管理」**画面（パス /{admin_prefix}/language_manager）を開きます。
  2. 編集する言語を選びます。position（グループ）で絞り込んだり、キーワードを入力してすばやく検索したりできます。 en 以外の言語を表示しているときは、比較できるように英語の原文が横に表示されます。
  3. 既存の文言を編集する: テキスト欄を直接編集して保存します。システムは location ＋ code の組で 該当する行を上書き（upsert）します。
  4. 新しい文言を追加する: 新規追加をクリックし、code（コード）と text を入力します。
    • ⚠️ 新しく追加した文言は、必ず最初に en ロケール用に作成されます（code は一意です）。その後、 他の言語を1つずつ開き、手順3で同じコードの翻訳を入力してください。

期待される結果: 保存したら、サイトや管理画面の該当ページを再読み込みしてください。新しい文言がすぐに 表示されます（DB が優先して読み込まれるためです）。変わらない場合は、表示中の正しいロケールを 編集しているか確認してください（2.1 章 を参照）。

4. 更新方法

ここでいう「言語の更新」とは、パッケージの既定の翻訳文字列を DB に反映し直すことです（例えば、 composer update で新しい文言や修正された文字列が入った後）。2つのモードがあり、あなたの編集内容を 上書きするかどうかが異なります。

実行方法 モード 影響
gp247:install / gp247:update insertOrIgnore（安全） 足りないコードを追加するだけです。あなたが編集した文言はそのまま残ります
gp247:language-update upsert（上書き） すべてのコードについて、テキストをパッケージの既定版に上書きします

安全な更新（編集内容を保持）

Composer でパッケージを更新した後に実行します。

php artisan gp247:update

このコマンドの言語処理のステップは、足りない翻訳文字列だけを追加し、管理画面でカスタマイズした文言には触れません。

上書き更新（パッケージの標準版に戻す）

php artisan gp247:language-update
  • コマンドは core → front → shop の順に自動で実行されます。インストールされていないパッケージはスキップします。
  • ⚠️ 注意: このコマンドは、管理画面で編集したすべての文言を上書きし、パッケージの最新の既定版に 戻します。多くカスタマイズしている場合は、実行前に languages テーブルをバックアップしてください。

ℹ️ 言語ファイル用の vendor:publish はありません。 翻訳文字列は、外部に公開される言語ファイルではなく、 DB に書き込む seeder で配布されます。そのため、標準の更新方法は上の2つの artisan コマンドです。

よくある質問（Q&A）

Q1: vendor/gp247/core/src/Lang/vi/... の言語ファイルを編集したのに、サイトの文言が変わりません。なぜですか？

→ 設計どおりの動作です。DB（languages）の内容は、ファイルより常に優先されます。ファイルを編集する代わりに、 管理画面 → 言語管理 で文言を編集してください。

Q2: 文言を1つ変えるには、どこで操作するのが一番早いですか？

→ 管理画面 → 「言語管理」（/language_manager）です。キーワードで絞り込み、その場で編集して保存します。 デプロイやコマンドの実行は不要です。

Q3: gp247:update と gp247:language-update の違いは何ですか？

→ gp247:update は安全です。言語のステップでは足りないコードを追加するだけで、あなたの編集内容は残ります。 gp247:language-update は、すべての文字列をパッケージの既定版に上書きします。カスタマイズを残したい → gp247:update を使います。最新の標準版に戻したい → gp247:language-update（または gp247:update --overwrite-lang）を実行します。事前のバックアップを忘れないでください。

Q4: 新しい言語を追加したのに、その言語ではサイトの文言が空のままです。なぜですか？

→ 言語の追加は admin_language に行を作るだけで、翻訳はまだありません。言語管理（3.3 章）でその ロケールの文言を入力するか、独自の seeder を用意する必要があります。

Q5: ベトナム語・英語を削除できないのはなぜですか？

→ 基本の2言語（vi、en）は、システムが常に予備として使える標準言語を持てるよう、定数 GP247_GUARD_LANGUAGE で保護されています。他の方法で表示をオフにすることはできますが、一覧から削除することはできません。

Q6: サイトの既定言語はどこで変更しますか？

→ 表示ロケールは session('locale') → ストアの既定言語 → config('app.locale') の順で優先されます。 サイト全体の既定を変えるには、ストアの既定言語（ストアの設定）と、必要に応じて .env の APP_LOCALE を変更してください。

Q7: GP247 は /vi/... のような URL で言語を判定しますか？

→ いいえ。言語は URL の接頭辞ではなく、session ＋ ストアの既定言語で制御されます。

Q8: languages テーブルの position は何のためにありますか？

→ 管理画面で文言を絞り込み・検索するためのグループのラベルです（例: action、store.admin）。 どの文言が表示されるかには影響しません。それは code ＋ location の組で決まります。

Q9: 翻訳文字列は長期間キャッシュされますか？

→ いいえ。あるのは 1リクエストの範囲のキャッシュだけです（ページの読み込みごとに、ロケールごとに DB へ 1回問い合わせます）。管理画面での編集は、次のページ読み込みからすぐに反映されます。

Q10: shop パッケージにはディスク上の言語フォルダーがありません。文言はどこから来るのですか？

→ shop のすべての文字列は DB（languages）にあり、インストール・更新時に DataShopLanguageSeeder が 読み込みます。そのため、shop にはディスク上の言語ファイルが必要ありません。

📅 最終更新: 2026-10-22 · ✍️ 作成者 (Author): GP247