多言語サポート

Grav の多言語サポートは、このテーマに関する素晴らしい コミュニティ・ディスカッション の結果です。ここでは、Grav の多言語対応について、どのようにセットアップすればよいのか、例を挙げて説明します。

英語以外の単一言語

もし、1つの言語しか使わないのであれば、翻訳を有効にして、 user/config/system.yaml ファイルに言語コードを追加してください。

languages:
  supported:
    - fr

or in the System configuration in the Admin:

Grav がフロントエンドで正しい言語文字列を使用することを確認します。
また、テーマが対応していれば、HTML タグにあなたの言語コードが追加されます。

Multi-Language Basics

Grav がどのようにフォルダ内のマークダウンファイルを使用してアーキテクチャ構造を定義し、コンテンツと同様に重要なページオプションを設定するかについては既にご存知のことと思いますので、これらの仕組みについて直接説明することはありません。 しかし、デフォルトでは Grav はページを表すためにフォルダ内の 単一の .md ファイルを探すことに注意してください。
この原則を十分に理解しているかどうか不安な場合は、先に進む前に 基本チュートリアル のセクションを参照してください。
多言語サポートが有効な場合、Grav は適切な言語ベースのファイル、例えば default.en.md や default.fr.md を探します。

Language Configuration

Gravがこれを行うには、まず user/config/system.yaml ファイルに基本的な言語設定を行う必要があります（読みやすいようにコメントをつけましょう）。

languages:
  supported: # Supported languages:
    - en # English language
    - fr # French language
  default_lang: en # デフォルトの言語を英語に設定する
  include_default_lang: true # true の場合、デフォルトの英語は/pathではなく、/en/pathを使用します。
[version=17]  include_default_lang_file_extension: true # true の場合、デフォルト言語として.md の代わりに.en.mdの拡張子を使用します。
  content_fallback:
    en: ['en'] # 英語にフォールバックしない。.
    fr: ['fr', 'en'] #  フランス語は、英語にフォールバックします。
[/version]

サポートする言語のリストを languages ブロックで提供することで、Grav 内での 多言語サポート を効果的に行うことができます。

この例では、2つの対応言語(en と fr)が記述されていることがわかります。これらにより、英語 と フランス語 の言語に対応することができます。

もし言語が（URLやコードによって）明示的に尋ねられなかった場合、Gravは提供された言語の順序を使用して正しい言語を選択します。 つまり、上記の例では default 言語は en または英語です。もし最初に fr を指定した場合は、フランス語がデフォルトの言語となります。

[version=17]
デフォルトでは、すべての言語はデフォルトの言語にフォールバックします。もし、そうしたくない場合は、 content_fallback を使用することで、言語のフォールバックを上書きすることができます。
[/version]

Multiple Language Pages

Gravのデフォルトでは、各ページは default.md のようなマークダウンファイルで表現されます。多言語サポートを有効にすると、Grav は適切な名前のマークダウン・ファイルを探します。 例えば、英語は私たちのデフォルト言語なので、まず default.en.md を探します。

[version=15]
このファイルが見つからない場合は、次の言語を試し、default.fr.mdを探します。 そのファイルが見つからない場合は、Gravのデフォルトにフォールバックし、ページの情報を提供するために default.md を探します。
[/version]
[version=16]
このファイルが見つからない場合は、次の言語を試し、default.fr.mdを探します。 そのファイルが見つからない場合は、Gravのデフォルトにフォールバックし、ページの情報を提供するために default.md を探します。
[/version]
[version=17]
そのファイルが見つからない場合は、Grav のデフォルトにフォールバックして、ページの情報を提供するためにdefault.mdを探します。

[/version]

最も基本的な Grav サイトが 01.home/default.md ファイル一つだとすると、まず default.md を default.en.md にリネームし、その中身は次のようになります。

---
title: Homepage
---

This is my Grav-powered homepage!

そして、同じ 01.home/ フォルダ内に default.fr.md という内容の新しいページを作ることができます。

---
title: Page d'accueil
---

Ceci est ma page d'accueil générée par Grav !

これで、現在のホームページを多言語で 2 ページ定義することができました。

[version=17]
既存のサイトを多言語に変換する場合、include_default_lang_file_extension: false を設定すると、主要言語用のプレーンな .md ファイル拡張子を使用し続けることができます。Read More... のように設定します。
[/version]

Active Language via URL

英語はデフォルトの言語なので、もし言語を指定せずにブラウザを動かすと、 default.en.md ファイルに記述されているような内容が表示されるでしょう。

http://yoursite.com/en

フランス語版へのアクセスは、もちろん、次のようになります。

http://yoursite.com/fr

Active Language via Browser

ほとんどのブラウザでは、コンテンツを表示する言語を設定できます。Grav はこの http_accept_language の値を読み取り、現在サポートされている言語と比較し、特定の言語が検出されなかった場合、あなたの好みの言語でコンテンツを表示する機能があります。

このオプションを有効にするには、user/system.yaml ファイルの languages: セクションで有効にする必要があります。

languages:
  http_accept_language: true

Session-Based Active Language

もし、アクティブな言語を URL から独立して記憶したい場合、アクティブな言語の session-based のストレージを有効にすることができます。 これを有効にするには、system.yamlで session: enabled: true を確実に設定する必要があります。 それから、言語設定を有効にする必要があります。

languages:
  session_store_active: true

これにより、アクティブな言語がセッションに保存されます。

Set Locale to the Active Language

この設定は、貨幣価値や日付、文字列の比較、文字の分類、その他のロケール特有の設定を制御する PHP の setlocale() メソッドを、アクティブな言語のものに設定するものです。 この値のデフォルトは false で、システムのロケールを使用します。この値を true に設定すると、ロケールを現在のアクティブな言語でオーバーライドします。

languages:
   override_locale: false

Default Language Prefix

デフォルトでは、すべての URL にデフォルトの言語コードがプレフィックスとして付加されます。 例えば、英語とフランス語 (en と fr) をサポートしていて、デフォルトが英語の場合。 ページルートは、英語では /en/my-page 、フランス語では /fr/ma-page のように表示されるかもしれません。しかし、デフォルトの言語がプレフィックスなしであることが望ましい場合が多いので、このオプションを false に設定すれば、英語のページは /my-page として表示されるようになります。

languages:
    include_default_lang: false

[version=17]

Default File Extension

既存のサイトを多言語に変換する場合、既存のすべてのページを新しい言語ファイル拡張子 .en.md に変換するのは大変な作業かもしれません（英語を使用している場合）。このような場合、元の言語の言語拡張を無効にすることができます。

languages:
    include_default_lang_file_extension: false

[/version]

Multi-Language Routing

Gravは通常、フォルダの名前を使用して、特定のページの URL ルートを生成します。 これにより、サイトアーキテクチャを容易に理解し、フォルダのネストされたセットとして実装することができます。 しかし、多言語サイトでは、その特定の言語でより意味のあるURLを使用したい場合があります。

If we had the following folder structure:

- 01.animals
  - 01.mammals
    - 01.bats
    - 02.bears
    - 03.foxes
    - 04.cats
  - 02.reptiles
  - 03.birds
  - 04.insets
  - 05.aquatic

この場合、http://yoursite.com/animals/mammals/bears のようなURLが生成されます。 これは英語のサイトでは素晴らしいことですが、もしフランス語のサイトも作りたいのであれば、適切に翻訳されたものが望ましいでしょう。これを実現する最も簡単な方法は、それぞれの fr.md ページファイルにカスタム slug を追加することです。例えば、哺乳類のページでは次のようになります。

---
title: Mammifères
slug: mammiferes
---

Les mammifères (classe des Mammalia) forment un taxon inclus dans les vertébrés, traditionnellement une classe, définie dès la classification de Linné. Ce taxon est considéré comme monophylétique...

他のファイルの適切な slug-overrides と組み合わせると、URL は http://yoursite.com/animaux/mammiferes/ours となり、よりフランス的な外観になります!

もう一つの方法は、page-level routes のサポートを利用し、ページの完全なルート・エイリアスを提供することです。

Language-Based Homepage

ホームページのルート / スラッグを上書きすると、Gravは system.yamlの home.alias オプションで定義されたホームページを見つけることができなくなります。これは /homepage を探すことになり、あなたのフランス語のホームページは /page-d-accueil というルートを持っているかもしれません。

Gravは多言語のホームページをサポートするために、 home.alias の代わりに使える新しいオプションがあります。それはシンプルな home.aliases で、以下のような感じです。

home:
  aliases:
    en: /homepage
    fr: /page-d-accueil

このように、Gravは、アクティブな言語が英語かフランス語である場合に、どのようにホームページへ誘導するかを知っています。

Language-Based Twig Templates

デフォルトでは、Gravはレンダリングに使用するTwigテンプレートを決定するために、マークダウンのファイル名を使用します。 これは多言語でも同じように動作します。 例えば、default.fr.md は default.html.twig という Twig ファイルを現在のテーマと Twig テンプレートパスを登録するプラグインの適切な Twig テンプレートパスで探します。 多言語の場合、Grav は現在アクティブな言語もパス構造に追加します。 つまり、言語固有のTwigファイルが必要な場合、ルートレベルの言語フォルダに置くだけでよいということです。 例えば、現在のテーマが templates/default.html.twig にあるテンプレートを使用している場合、templates/fr/ フォルダを作成し、そこにフランス語固有のTwigファイルを置くことができます。templates/fr/default.html.twig` とします。

手動で設定する必要があるもう一つの方法は、ページヘッダーの template: 設定をオーバーライドすることです。例えば、

template: default.fr

これは templates/default.fr.html.twig にあるテンプレートを探します。

これにより、言語固有のTwigオーバーライドを提供するための2つのオプションが提供されます。

Translation via Twig

これらの翻訳文字列をTwigテンプレートで使う最も簡単な方法は、 |t Twigフィルタを使うことです。 t()` Twig 関数も使えますが、率直に言って、フィルタの方がすっきりしていて、同じ結果になります。

<h1 id="site-name">{{ "SITE_NAME"|t|e }}</h1>
<section id="header">
    <h2>{{ "HEADER.MAIN_TEXT"|t|e }}</h2>
    <h3>{{ "HEADER.SUB_TEXT"|t|e }}</h3>
</section>

Twigの関数 t() を使っても、同様の解答が得られます。

<h1 id="site-name">{{ t("SITE_NAME")|e }}</h1>
<section id="header">
    <h2>{{ t("HEADER.MAIN_TEXT")|e }}</h2>
    <h3>{{ t("HEADER.SUB_TEXT")|e }}</h3>
</section>

もう一つの新しい Twig フィルタ/関数では、配列から翻訳することができます。 これは特に、年の月や曜日のような値のリストを持っている場合に便利です。 例えば、次のような翻訳があるとします。

en:
  GRAV:
    MONTHS_OF_THE_YEAR: [January, February, March, April, May, June, July, August, September, October, November, December]

以下のようにすれば、投稿月に応じた適切な訳語を得ることができます。

{{ 'GRAV.MONTHS_OF_THE_YEAR'|ta(post.date|date('n') - 1)|e }}

また、ta()で Twig の関数として使用することもできます。

Translations with Variables

PHP's の sprintf(https://php.net/sprintf) 構文を使って、Twig の翻訳で変数を使用することもできます。

SIMPLE_TEXT: There are %d monkeys in the %s

そして、それらの変数に Twig を投入することができます。

{{ "SIMPLE_TEXT"|t(12, "London Zoo")|e }}

翻訳の結果:

There are 12 monkeys in the London Zoo

Complex Translations

時には、特定の言語で置換を伴う複雑な翻訳を行うことが必要になることがあります。 言語オブジェクトの translate() メソッドのフルパワーを tl フィルタ/関数で利用することができます。例えば

{{ ["SIMPLE_TEXT", 12, 'London Zoo']|tl(['fr'])|e }}

SIMPLE_TEXT の文字列を翻訳し、プレースホルダーをそれぞれ 12 と London Zoo に置き換えます。 また、最初に見つけた言語から順に、翻訳を試みる配列が渡されます。 これはフランス語で結果を出力します。

Il y a 12 singes dans le Zoo de Londres

PHP Translations

Twig のフィルタや関数と同様に、Grav のプラグインでも同じアプローチを使うことができます。

$translation = $this->grav['language']->translate(['HEADER.MAIN_TEXT']);

また、言語を指定することも可能です。

$translation = $this->grav['language']->translate(['HEADER.MAIN_TEXT'], 'fr');

配列の特定の項目を翻訳するには、次のようにします。

$translation = $this->grav['language']->translateArray('GRAV.MONTHS_OF_THE_YEAR', 3);

Plugin and Theme Language Translations

また、プラグインやテーマの中で独自の翻訳を提供することもできます。 プラグインやテーマのルートに languages.yaml ファイルを作成します (例: /user/plugins/error/languages.yaml や user/themes/antimatter/languages.yaml) このファイルには言語やロケールのコードをプレフィックスとしてサポートするすべての言語が含まれていなければなりません。

en:
  PLUGIN_ERROR:
    TITLE: Error Plugin
    DESCRIPTION: The error plugin provides a simple mechanism for handling error pages within Grav.
fr:
  PLUGIN_ERROR:
    TITLE: Plugin d'Erreur
    DESCRIPTION: Le plugin d'erreur fournit un mécanisme simple de manipulation des pages d'erreur au sein de Grav.

Translation Overrides

もし、特定の翻訳を上書きしたい場合は、 user/languages/ フォルダ内の適切な言語ファイルに、変更したキーと値のペアを置くだけです。 例えば、 user/languages/ja.yaml というファイルには、次のような内容を記述することができます。

PLUGIN_ERROR:
  TITLE: My Error Plugin

これにより、プラグインやテーマ自体に手を加えることなく、常に翻訳文字列を上書きできるようになり、また、アップデート時にカスタム翻訳を上書きすることもなくなります。

Advanced

Environment-Based Language Handling

Grav の環境設定](../../advanced/environment-config) を利用すると、URLに基づいて自動的に正しいバージョンのサイトへ誘導することができます。 例えば、http://french.mysite.comのようなURLで、標準のhttp://www.mysite.comのエイリアスがあった場合、環境設定を行うことができます。

/user/french.mysite.com/config/system.yaml

languages:
  supported:
    - fr
    - en

これは、inverted language order を使用しているため、デフォルトの言語がfrになり、フランス語がデフォルトで表示されるようになりました。

Language Alias Routes

各ページは独自のカスタムルートを持つことができるため、同じページの異なる言語バージョン間で切り替えるのは難しいでしょう。 しかし、Page オブジェクトには新しい Page.rawRoute() メソッドがあり、1 つのページのさまざまな言語翻訳のどれに対しても同じ生のルートを取得します。 あなたがしなければならないことは、ページの特定の言語バージョンへの適切なルートを得るために、langコードを前に置くことです。

例えば、英語のページで、カスタムルートがあるとします。

/my-custom-english-page

フランス語のページには、カスタムルートが

/ma-page-francaise-personnalisee

英語ページの生ページを取得すると、このようになるかもしれない。

/blog/custom/my-page

そして、あなたが望む言語を追加するだけで、それがあなたの新しいURLになります。

/fr/blog/custom/my-page

これは /ma-page-francaise-personnalisee と同じページを取得します。

Translation Support

Grav は Twig で、またテーマやプラグインで使用するために PHP を介して翻訳を提供するための、シンプルで強力なメカニズムを提供します。これはデフォルトで有効になっており、言語が定義されていない場合は en 言語が使用されます。 手動で翻訳を有効・無効にするには、system.yaml に設定があります。

languages:
  translations: true

翻訳には、 system.yaml の languages: supported: で定義されたものと同じ言語のリストが使用されます。

翻訳システムは Grav の設定と同様の方法で動作し、翻訳を提供できる場所と方法がいくつかあります。

Grav が最初に翻訳ファイルを探す場所は、system/languages フォルダです。ファイルは以下のような形式で作成されることが期待されます。ファイルは、 en.yaml や fr.yaml といったフォーマットで作成されることが期待されます。 各 yaml ファイルには、キーと値のペアの配列またはネストされた配列が含まれている必要があります。

SITE_NAME: My Blog Site
HEADER:
    MAIN_TEXT: Welcome to my new blog site
    SUB_TEXT: Check back daily for the latest news

翻訳されていない文字列を判別しやすくするため、また Twig テンプレートで使用する際に分かりやすくするために、Gravは大文字の言語文字列を使用することを好みます。

Grav には、アクティブな言語の翻訳が見つからない場合に、サポートされている言語をフォールバックして翻訳を見つける機能があります。 これはデフォルトで有効になっていますが、 translations_fallback オプションで無効にすることができます。

languages:
  translations_fallback: true

Language Switcher

シンプルなLanguage Switchingプラグインは、Admin Plugin から、または GPM からダウンロードすることができます。

bin/gpm install langswitcher

設定や実装のためのドキュメントはGitHubで公開されています.

Setup with Language Specific Domains

ドメインにデフォルト言語（第一言語）を割り当てるために、Environment-Based Language Handling でサイトを構成します。

オプションを確認してください。

pages.redirect_default_route: true

system.yaml で true に設定が確認できます。

以下を .htaccess ファイルに追加し、言語スラッグとドメイン名を必要なものに採用します。

# http://www.cheat-sheets.org/saved-copy/mod_rewrite_cheat_sheet.pdf
# http://www.workingwith.me.uk/articles/scripting/mod_rewrite

# handle top level e.g. http://grav-site.com/de
RewriteRule ^en/?$ "http://grav-site.com" [R=302,L]
RewriteRule ^de/?$ "http://grav-site.de" [R=302,L]

# handle sub pages, exclude admin path
RewriteCond %{REQUEST_URI} !(admin) [NC]
RewriteRule ^en/(.*)$ "http://grav-site.com/$1" [R=302,L]
RewriteCond %{REQUEST_URI} !(admin) [NC]
RewriteRule ^de/(.*)$ "http://grav-site.de/$1" [R=302,L]

If you know how to simplify the rewrite rules, please edit this page on GitHub by clicking the Edit link at the top of the page.

Language Logic in Twig Templates

Twig テンプレートから言語ステートとロジックにアクセスする必要性がよくあります。 例えば、特定の言語ごとに異なる名前の画像ファイル（myimage.en.jpg と myimage.fr.jpg ）にアクセスする必要がある場合などです。

正しいバージョンの画像を表示するためには、現在アクティブな言語を知っておく必要があります。 Grav では、 Grav オブジェクトを介して Language オブジェクトにアクセスし、適切なメソッドを呼び出すことで可能です。上記の例では、次のようなTwigコードで実現することができます。

{{ page.media.images['myimage.'~grav.language.getActive~'.jpg'].html()|raw }}

Twig の getActive 呼び出しは、効果的に Language->getActive() を呼び出して、現在アクティブな言語コードを返します。 いくつかの便利な言語メソッドがあります。

• getLanguages() - Returns an array of all supported languages
• getLanguage() - Returns current active, else returns default language
• getActive() - Returns current active language
• getDefault() - Returns the default (first) language

利用可能なメソッドの完全なリストは、<grav root>/system/src/Grav/Common/Language/Language.php ファイルを参照することができます。