# vue: initializeGTSPA
URL: https://generaltranslation.com/ja/docs/vue/reference/functions/initialize-gt-spa.mdx
---

title: initializeGTSPA
description: モジュールレベルでの翻訳用に、ブラウザ専用の Vue SPA ランタイムを初期化してプリロードします。initializeGTSPA の API リファレンス。

---

このイニシャライザはページ全体で単一のランタイムを管理し、読み込んだカタログを同期的な [`t()`](/docs/vue/reference/functions/t) 呼び出しで利用できるようにします。コンポーネント内の [`useGT()`](/docs/vue/reference/composables/use-gt) コールバックを補完するものであり、composable を置き換えるものではなく、サーバーレンダリングもサポートしません。

## 概要 [#overview]

```ts
function initializeGTSPA(
  options?: InitializeGTSPAOptions
): Promise<GTPlugin>;
```

[`t()`](/docs/vue/reference/functions/t) を呼び出すモジュールをインポートする前にイニシャライザの完了を待ち、返されたプラグインをそのままインストールします。

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-vue';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

async function bootstrap() {
  const gt = await initializeGTSPA({ ...gtConfig, loadTranslations });
  const { mount } = await import('./main');
  mount(gt);
}

void bootstrap().catch((error: unknown) => {
  console.error(error);
});
```

## パラメータ [#parameters]

| パラメータ     | 説明                                                     | 型                                                                               | 任意 | デフォルト |
| --------- | ------------------------------------------------------ | ------------------------------------------------------------------------------- | -- | ----- |
| `options` | SPA のロケール、cookie、mapping、allowlist、カタログ loader の設定。 | [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options) | はい | `{}`  |

| オプション              | 説明                                                                              | 型                                                                     | 任意 | デフォルト                       |
| ------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -- | --------------------------- |
| `defaultLocale`    | ソースロケールおよび代替ロケール。                                                               | `string`                                                              | はい | `en`                        |
| `loadTranslations` | 非同期のターゲットカタログ loader。                                                       | [`LoadTranslations`](/docs/vue/reference/types/load-translations)     | はい | 空のカタログ                  |
| `locale`           | 明示的に指定する初期ロケール。ブラウザの cookie より優先されます。                                           | `string`                                                              | はい | Cookie、次に `defaultLocale`   |
| `localeCookieName` | ロケール選択を保持するための Cookie。                                                          | `string`                                                              | はい | `generaltranslation.locale` |
| `locales`          | 設定、cookie、setter で受け付けるターゲットロケール。                                               | `readonly string[]`                                                   | はい | 制限なし                        |
| `customMapping`    | ロケール matching および formatter locale resolution に使用する `code` 値を mapping するオブジェクト。 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | はい | なし                          |

`locales` には通常、`gt.config.json` のターゲットロケールが含まれます。イニシャライザはサポート対象に `defaultLocale` を追加します。解決の詳細については、[`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options) を参照してください。

## 初期化 [#initialization]

最初の呼び出しによってページ全体の初期化が開始され、そのオプションが適用されます。同時に行われる呼び出しは同じ Promise を共有します。初期化が成功すると、それ以降のすべての呼び出しは同じ [`GTPlugin`](/docs/vue/reference/types/gt-plugin) を返し、新たに指定されたオプションは無視されます。

初期化では、完了前に次の手順を実行します。

1. 明示的に指定されたロケール、保存済みの cookie、またはデフォルトロケールを、`locales` と `customMapping` に基づいて解決します。
2. ページの存続期間中、アクティブなロケールが固定されるランタイムを作成します。
3. アクティブなターゲットカタログを読み込んでキャッシュします。デフォルトロケールではソースコンテンツを使用するため、loader は実行されません。
4. ランタイムをモジュールレベルの [`t()`](/docs/vue/reference/functions/t) 呼び出しで利用できるようにします。

読み込みが失敗した場合、初期化は loader の診断情報をログに記録して失敗します。失敗した試行は singleton にならないため、後続の呼び出しで再試行できます。

## ロケールの変更 [#locale-changes]

返されるプラグインでは、リロード遷移が使用されます。`plugin.setLocale(locale)` または [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) を呼び出すと、指定したロケールを解決し、設定されている cookie に書き込んでからドキュメントをリロードします。

現在のページでは、リロードされるまで固定されたロケールが維持されます。次回のブートストラップでは新しい cookie からロケールが解決され、アプリケーションモジュールの実行前にそのカタログがプリロードされるため、すべてのモジュールレベルでの翻訳が再評価されます。セッターがリロード前にターゲットカタログを現在のページに読み込むことはありません。

`locales` が指定されている場合、照合では大文字と小文字が区別されず、canonical alias がサポートされます。loader のパスには `gt.config.json` での表記が保持されます。保存済みまたは指定された未対応のロケールは `defaultLocale` に解決されます。`locales` を省略した場合、デフォルト以外のロケールコードは制限されません。

## 戻り値とエラー [#return-errors]

**戻り値** `Promise<`[`GTPlugin`](/docs/vue/reference/types/gt-plugin)`>`

この Promise は、初期ロケールの準備が完了してから解決されます。このプラグインそのものをインストールしてください。別の [`createGT()`](/docs/vue/reference/functions/create-gt) インスタンスを作成すると、コンポーネントで使用されるロケールとカタログキャッシュが [`t()`](/docs/vue/reference/functions/t) のものと異なります。

ブラウザのグローバル状態とドキュメントの再読み込みはリクエストセーフではないため、サーバーレンダリング環境では返された Promise が拒否されます。サーバーレンダリングでは、リクエストスコープの [`createGT({ locale })`](/docs/vue/reference/functions/create-gt#server-rendering) プラグインを 1 つ使用し、コンポーネント内では [`useGT()`](/docs/vue/reference/composables/use-gt) を使用してください。

## 例 [#example]

通常の Vue エントリポイントは、マウント関数の内側に置きます。

```ts title="src/main.ts"
import { createApp } from 'vue';
import type { GTPlugin } from 'gt-vue';
import App from './App.vue';

export function mount(gt: GTPlugin) {
  createApp(App).use(gt).mount('#app');
}
```

後続の動的インポートで読み込まれるモジュールは、評価時に翻訳できます。

```ts title="src/navigation.ts"
import { t } from 'gt-vue';

export const navigation = [
  { label: t('Documentation'), href: '/docs' },
  { label: t('Settings'), href: '/settings' },
];
```