コンテンツ宣言ファイルの翻訳を自動入力

CI でのコンテンツ宣言ファイルの自動入力は、開発ワークフローを高速化する方法です。

動作の理解

fill コマンドには2つのモードがあります：

• Complete: 各ロケールのすべての欠落コンテンツを自動的に入力し、現在のファイルまたは指定された別のファイルを編集します。つまり、完全モードは既に翻訳されている既存コンテンツのスキップします。
• Review: 各ロケールのすべてのコンテンツを自動的に入力し、特定のファイルまたは指定された別のファイルを生成します。

fill コマンドはすべてのロケールコンテンツ宣言ファイルを処理します。つまり、CMSからのリモートコンテンツは処理しません。CMSは独自の翻訳管理を含んでいます。 @intlayer/sync-json-plugin などのプラグインを使用する場合、Intlayerはこれらのファイルをロケールコンテンツ宣言ファイルに変換します。つまり、これらのファイルは fill コマンドによって処理されます。

新しく生成されたファイルには、辞書メタデータとして filled 命令が含まれています。この命令は、Intlayerがファイルが自動入力されたかどうかを判定し、存在する場合はこのファイルを再度翻訳の対象からスキップするために使用されます。

Intlayerは自動入力に関して以下の命令を考慮します：

• .content.{ts|js|json} ファイルから → fill 命令
• 設定ファイル .intlayer.config.ts から → dictionary.fill 命令
• それ以外の場合はデフォルトで true に設定されます

ロケール固有のコンテンツ宣言ファイルの場合、true 命令は ./{{fileName}}.fill.content.json に置き換えられます。これは、ロケール固有のコンテンツ宣言ファイルが追加のローカライズされたコンテンツを受け取ることができないためです。そのため、既存のファイルを上書きしないために新しいファイルを生成します。

デフォルト動作

デフォルトでは、fillはグローバルにtrueに設定されています。これは、Intlayerがすべてのコンテンツファイルを自動的に入力し、ファイル自体を編集することを意味します。この動作は、いくつかの方法でカスタマイズできます。

グローバル設定オプション

1. fill: true (デフォルト) - すべてのロケールを自動的に埋め、現在のファイルを編集します
2. fill: false - このコンテンツファイルの自動埋めを無効にします
3. fill: "./relative/path/to/file" - 現在のファイルを編集せずに指定されたファイルを作成/更新します。相対パスは現在のファイルの場所に基づいて解決されます
4. fill: "/absolute/path/to/file" - 現在のファイルを編集せずに指定されたファイルを作成/更新します。相対パスは基本ディレクトリの場所に基づいて解決されます（設定ファイル .intlayer.config.ts の baseDir フィールド）
5. fill: "C:\absolute\path\to\file" - 現在のファイルを編集せずに指定されたファイルを作成/更新します。絶対パスはお使いのオペレーティングシステムに基づいて解決されます
6. fill: { [key in Locales]?: string } - 各ロケールについて指定されたファイルを作成/更新します

v7 の動作変更

v7 では、fill コマンドの動作が更新されました：

• fill: true - 現在のファイルを全ロケールの埋め込みコンテンツで上書きします
• fill: "path/to/file" - 指定されたファイルを埋め込みますが、現在のファイルは変更しません
• fill: false - 自動埋め込みを完全に無効にします

別のファイルに書き込むためのパスオプションを使用する場合、埋め込みメカニズムはコンテンツ宣言ファイル間の マスター・スレーブ 関係を通じて機能します。メインファイル（マスター）が情報源として機能し、更新されると、Intlayer はパスで指定されたスレーブの宣言ファイルに変更を自動的に適用します。

ロケールごとのカスタマイズ

オブジェクトを使用して、各ロケールの動作をカスタマイズすることもできます：

const config: IntlayerConfig = {
  content: {
    internationalization: {
      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
      defaultLocale: Locales.ENGLISH,
      requiredLocales: [Locales.ENGLISH], // Property 'pl' is missing in type '{ en: string; xxx } on your t function if を回避することをお勧めします
    },
  },
  dictionary: {
    fill: {
      en: true, // 英語の現在のファイルを埋める・編集する
      fr: "./translations/fr.json", // フランス語用に別ファイルを作成
      es: false, // スペイン語の埋めを無効にする
    },
  },
};

これにより、同じプロジェクト内の異なるロケールに対して異なるfill動作を設定できます。

import { Locales, type Dictionary } from "intlayer";

const exampleContent = {
  key: "example",
  locale: Locales.ENGLISH,
  fill: "./example.content.json",
  content: {
    contentExample: "This is an example of content",
  },
} satisfies Dictionary;

export default exampleContent;

ここに fill 命令を使用したロケール単位のコンテンツ宣言ファイルがあります。

次に、以下のコマンドを実行します：

npx intlayer fill --file 'src/components/example/example.content.ts'

Intlayerは src/components/example/example.content.json に派生宣言ファイルを自動生成し、メインファイルでまだ宣言されていないすべてのロケールを埋めます。

{
  "key": "example",
  "content": {
    "contentExample": {
      "nodeType": "translation",
      "translation": {
        "fr": "Ceci est un exemple de contenu",
        "es": "Este es un ejemplo de contenido",
      },
    },
  },
}

その後、両方の宣言ファイルが単一の辞書にマージされ、標準の useIntlayer("example") hook（react）/composable（vue）を使用してアクセスできます。

グローバル設定

intlayer.config.ts ファイルでグローバル自動入力設定を構成できます。

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
  },
  dictionary: {
    // すべての辞書に対して欠落している翻訳を自動生成します
    fill: "./{{fileName}}Filled.content.ts",
    //
    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
    //
    // fill: true, // "./{{fileName}}.content.json" を使用しているようなすべての辞書に対して欠落している翻訳を自動生成します
    //
    // fill: {
    //   en: "./{{fileName}}.en.content.json",
    //   fr: "./{{fileName}}.fr.content.json",
    //   es: "./{{fileName}}.es.content.json",
    // },
  },
};

export default config;

コンテンツファイルの fill フィールドを使用して、辞書ごとに細かく調整することもできます。Intlayer は最初に辞書ごとの設定を検討し、その後グローバル設定にフォールバックします。

自動補完されたファイル形式

自動補完された宣言ファイルに推奨される形式は JSON であり、これによりフォーマットの制約を回避できます。ただし、Intlayer は .ts、.js、.mjs、.cjs などの他の形式もサポートしています。

const exampleContent = {
  key: "example",
  autoFill: "./example.filled.content.ts",
  content: {
    // あなたのコンテンツ
  },
};

これにより、以下のファイルが生成されます：

src/components/example/example.filled.content.ts

.js、.ts、および類似のファイルの生成は以下のように動作します：

• ファイルがすでに存在する場合、Intlayer は AST（抽象構文木）を使用して各フィールドを特定し、欠落している翻訳を挿入します。
• ファイルが存在しない場合、Intlayerはデフォルトのコンテンツ宣言ファイルテンプレートを使用して生成します。

絶対パス

autoFill フィールドは絶対パスもサポートしています。

const exampleContent = {
  key: "example",
  autoFill: "/messages/example.content.json",
  content: {
    // あなたのコンテンツ
  },
};

これにより、以下のファイルが生成されます：

/messages/example.content.json

ロケール別コンテンツ宣言ファイルの自動生成

autoFill フィールドは、ロケール別のコンテンツ宣言ファイルの生成もサポートしています。

const exampleContent = {
  key: "example",
  autoFill: {
    fr: "./example.fr.content.json",
    es: "./example.es.content.json",
  },
  content: {
    // あなたのコンテンツ
  },
};

これにより、2つの別々のファイルが生成されます：

• src/components/example/example.fr.content.json
• src/components/example/example.es.content.json

この場合、オブジェクトにすべてのロケールが含まれていない場合、Intlayerは残りのロケールの生成をスキップします。

特定のロケールの自動入力をフィルタリングする

autoFill フィールドにオブジェクトを使用すると、フィルターを適用して特定のロケールファイルのみを生成できます。

const exampleContent = {
  key: "example",
  autoFill: {
    fr: "./example.fr.content.json",
  },
  content: {
    // あなたのコンテンツ
  },
};

これにより、フランス語の翻訳ファイルのみが生成されます。

パス変数

autoFill パス内で変数を使用して、生成されるファイルのターゲットパスを動的に解決することができます。

使用可能な変数:

• {{locale}} – ロケールコード（例: fr, es）
• {{fileName}} – ファイル名（例: index）
• {{key}} – 辞書キー（例: example）

const exampleContent = {
  key: "example",
  autoFill: "/messages/{{locale}}/{{key}}.content.json",
  content: {
    // あなたのコンテンツ
  },
};

これにより、以下のファイルが生成されます:

• /messages/fr/example.content.json
• /messages/es/example.content.json

const exampleContent = {
  key: "example",
  autoFill: "./{{fileName}}.content.json",
  content: {
    // あなたのコンテンツ
  },
};

これにより、以下のファイルが生成されます:

• ./index.content.json
• ./index.content.json