Intlayerの今後のリリースに関する通知を受け取る

    このページのコンテンツはAIを使用して翻訳されました。

    英語の元のコンテンツの最新バージョンを見る

    Intlayer と Vite と Vue で国際化(i18n)を始める

    GitHub の アプリケーションテンプレート を参照してください。

    Intlayer とは?

    Intlayer は、最新のウェブアプリケーションにおける多言語対応を簡素化するために設計された革新的なオープンソースの国際化(i18n)ライブラリです。

    Intlayer を使うと、以下が可能です:

    • コンポーネントレベルで宣言的な辞書を使い、翻訳を簡単に管理できます。
    • メタデータ、ルート、コンテンツを動的にローカライズできます。
    • 自動生成された型により TypeScript サポートを確保し、オートコンプリートやエラー検出を向上させます。
    • 動的なロケール検出や切り替えなどの高度な機能を利用できます。

    Vite と Vue アプリケーションに Intlayer をセットアップするステップバイステップガイド

    ステップ 1: 依存パッケージのインストール

    npm を使って必要なパッケージをインストールします:

    bash
    npm install intlayer vue-intlayernpm install --save-dev vite-intlayer
    • intlayer

      設定管理、翻訳、コンテンツ宣言、トランスパイル、およびCLIコマンドのための国際化ツールを提供するコアパッケージです。

    • vue-intlayer IntlayerをVueアプリケーションに統合するパッケージです。Vueの国際化のためのコンテキストプロバイダーとコンポーザブルを提供します。

    • vite-intlayer

    Viteバンドラー(Vite bundler)とIntlayerを統合するためのViteプラグイン、およびユーザーの優先ロケールの検出、クッキー管理、URLリダイレクト処理のためのミドルウェアを含みます。

    ステップ2: プロジェクトの設定

    アプリケーションの言語を設定するための設定ファイルを作成します:

    intlayer.config.ts
    import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // 他のロケールを追加    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

    この設定ファイルを通じて、ローカライズされたURL、ミドルウェアのリダイレクション、クッキー名、コンテンツ宣言の場所と拡張子、コンソールでのIntlayerログの無効化などを設定できます。利用可能なパラメータの完全なリストについては、設定ドキュメントを参照してください。

    ステップ3: Vite設定にIntlayerを統合する

    intlayerプラグインを設定に追加します。

    vite.config.ts
    import { defineConfig } from "vite";import vue from "@vitejs/plugin-vue";import { intlayerPlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [vue(), intlayerPlugin()],});

    intlayerPlugin() Viteプラグインは、IntlayerをViteと統合するために使用されます。これにより、コンテンツ宣言ファイルのビルドが保証され、開発モードでそれらを監視します。また、Viteアプリケーション内でIntlayerの環境変数を定義します。さらに、パフォーマンスを最適化するためのエイリアスも提供します。

    ステップ4: コンテンツを宣言する

    翻訳を格納するためのコンテンツ宣言を作成および管理します:

    src/helloWorld.content.ts
    import { t, type Dictionary } from "intlayer";const helloWorldContent = {  key: "helloworld",  content: {    count: t({ en: "count is ", fr: "le compte est ", es: "el recuento es " }),    edit: t({      en: "Edit <code>components/HelloWorld.vue</code> and save to test HMR",      fr: "Éditez <code>components/HelloWorld.vue</code> et enregistrez pour tester HMR",      es: "Edita <code>components/HelloWorld.vue</code> y guarda para probar HMR",    }),    checkOut: t({      en: "Check out ",      ja: "チェックしてください ",      fr: "Vérifiez ",      es: "Compruebe ",    }),    officialStarter: t({      en: ", the official Vue + Vite starter",      ja: ", 公式の Vue + Vite スターターです",      fr: ", le starter officiel Vue + Vite",      es: ", el starter oficial Vue + Vite",    }),    learnMore: t({      en: "Learn more about IDE Support for Vue in the ",      ja: "Vue の IDE サポートについて詳しくは ",      fr: "En savoir plus sur le support IDE pour Vue dans le ",      es: "Aprenda más sobre el soporte IDE para Vue en el ",    }),    vueDocs: t({      en: "Vue Docs Scaling up Guide",      ja: "Vue ドキュメント スケーリングアップガイド",      fr: "Vue Docs Scaling up Guide",      es: "Vue Docs Scaling up Guide",    }),    readTheDocs: t({      en: "Click on the Vite and Vue logos to learn more",      fr: "Cliquez sur les logos Vite et Vue pour en savoir plus",      es: "Haga clic en los logotipos de Vite y Vue para obtener más información",      ja: "詳細を知るには、Vite と Vue のロゴをクリックしてください",    }),  },} satisfies Dictionary;export default helloWorldContent;

    コンテンツ宣言は、contentDir ディレクトリ(デフォルトは ./src)に含まれている限り、アプリケーションのどこにでも定義できます。また、コンテンツ宣言のファイル拡張子(デフォルトは .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx})に一致している必要があります。

    詳細については、コンテンツ宣言のドキュメントを参照してください。

    ステップ5: コード内でIntlayerを利用する

    Vueアプリケーション全体でIntlayerの国際化機能を利用するには、まずメインファイルでIntlayerのシングルトンインスタンスを登録する必要があります。このステップは非常に重要で、アプリケーション内のすべてのコンポーネントに国際化コンテキストを提供し、コンポーネントツリーのどこからでも翻訳にアクセスできるようにします。

    import { createApp } from "vue";import { installIntlayer } from "vue-intlayer";import App from "./App.vue";import "./style.css";const app = createApp(App);// 最上位でプロバイダーを注入installIntlayer(app);// アプリをマウントapp.mount("#app");

    メインのVueコンポーネントを作成し、useIntlayerのコンポーザブルを使用することで、アプリケーション全体でコンテンツ辞書にアクセスできます。

    src/HelloWord.vue
    <script setup lang="ts">import { ref } from "vue";import { useIntlayer } from "vue-intlayer";defineProps({  msg: String,});const {  count,  edit,  checkOut,  officialStarter,  learnMore,  vueDocs,  readTheDocs,} = useIntlayer("helloworld");const countRef = ref(0);</script><template>  <h1>{{ msg }}</h1>  <div class="card">    <button type="button" @click="countRef++">      <count />      {{ countRef }}    </button>    <p v-html="edit"></p>  </div>  <p>    <checkOut />    <a href="https://vuejs.org/guide/quick-start.html#local" target="_blank"      >create-vue</a    >, <officialStarter />  </p>  <p>    <learnMore />    <a      href="https://vuejs.org/guide/scaling-up/tooling.html#ide-support"      target="_blank"      ><vueDocs /></a    >.  </p>  <p class="read-the-docs"><readTheDocs /></p>  <p class="read-the-docs">{{ readTheDocs }}</p></template>

    Intlayerでのコンテンツへのアクセス

    Intlayerは、コンテンツにアクセスするためのさまざまなAPIを提供しています:

    • コンポーネントベースの構文(推奨): <myContent /> または <Component :is="myContent" /> の構文を使用して、Intlayerノードとしてコンテンツをレンダリングします。これはビジュアルエディターCMSとシームレスに統合されます。

    • 文字列ベースの構文{{ myContent }} を使用して、ビジュアルエディターのサポートなしにプレーンテキストとしてコンテンツをレンダリングします。

    • 生のHTML構文<div v-html="myContent" /> を使用して、Visual Editor のサポートなしでコンテンツを生の HTML としてレンダリングします。

    • 分割代入構文: useIntlayer コンポーザブルはコンテンツを持つ Proxy を返します。この Proxy はリアクティビティを保ったままコンテンツにアクセスするために分割代入できます。

      • const content = useIntlayer("myContent");{{ content.myContent }} / <content.myContent /> を使用します。
      • または const { myContent } = useIntlayer("myContent");{{ myContent }} / <myContent/> を使用してコンテンツを分割代入します。

    (オプション)ステップ6: コンテンツの言語を変更する

    コンテンツの言語を変更するには、useLocale コンポーザブルが提供する setLocale 関数を使用します。この関数により、アプリケーションのロケールを設定し、それに応じてコンテンツを更新できます。

    言語を切り替えるコンポーネントを作成します:

    src/components/LocaleSwitcher.vue
    <template>  <div class="locale-switcher">    <select v-model="selectedLocale" @change="changeLocale">      <option v-for="loc in availableLocales" :key="loc" :value="loc">        {{ getLocaleName(loc) }}      </option>    </select>  </div></template><script setup lang="ts">import { ref, watch } from "vue";import { getLocaleName } from "intlayer";import { useLocale } from "vue-intlayer";// ロケール情報と setLocale 関数を取得const { locale, availableLocales, setLocale } = useLocale();// ref で選択されたロケールを追跡const selectedLocale = ref(locale.value);// 選択が変更されたときにロケールを更新const changeLocale = () => setLocale(selectedLocale.value);// selectedLocaleをグローバルなlocaleと同期させるwatch(  () => locale.value,  (newLocale) => {    selectedLocale.value = newLocale;  });</script>

    次に、このコンポーネントをApp.vueで使用します:

    src/App.vue
    <script setup lang="ts">import { useIntlayer } from "vue-intlayer";import HelloWorld from "@components/HelloWorld.vue";import LocaleSwitcher from "@components/LocaleSwitcher.vue";import { ref, watch } from "vue";const content = useIntlayer("app"); // 関連するintlayer宣言ファイルを作成</script><template>  <div>    <LocaleSwitcher />    <a href="https://vite.dev" target="_blank">      <img src="/vite.svg" class="logo" :alt="content.viteLogo" />    </a>    <a href="https://vuejs.org/" target="_blank">      <img src="./assets/vue.svg" class="logo vue" :alt="content.vueLogo" />    </a>  </div>  <HelloWorld :msg="content.title" /></template>

    (オプション)ステップ7: アプリケーションにローカライズされたルーティングを追加する

    Vueアプリケーションにローカライズされたルーティングを追加するには、通常、ロケールプレフィックス付きのVue Routerを使用します。これにより、各言語ごとにユニークなルートが作成され、SEOやSEOに適したURLに役立ちます。

    例:

    plaintext
    - https://example.com/about- https://example.com/es/about- https://example.com/fr/about

    まず、Vue Routerをインストールします:

    bash
    npm install intlayer vue-router

    次に、ロケールベースのルーティングを処理するルーター設定を作成します:

    src/router/index.ts
    import {  configuration,  getPathWithoutLocale,  localeFlatMap,  type Locales,} from 'intlayer';import { createIntlayerClient } from 'vue-intlayer';import { createRouter, createWebHistory } from 'vue-router';import HomeView from './views/home/HomeView.vue';import RootView from './views/root/Root.vue';// 国際化設定を取得const { internationalization, middleware } = configuration;const { defaultLocale } = internationalization;/** * ロケール固有のパスとメタデータを持つルートを宣言します。 */const routes = localeFlatMap((localizedData) => [  {    path: `${localizedData.urlPrefix}/`,    name: `Root-${localizedData.locale}`,    component: RootView,    meta: {      locale: localizedData.locale,    },  },  {    path: `${localizedData.urlPrefix}/home`,    name: `Home-${localizedData.locale}`,    component: HomeView,    meta: {      locale: localizedData.locale,    },  },]);// ルーターインスタンスを作成export const router = createRouter({  history: createWebHistory(),  routes,});// ロケール処理のためのナビゲーションガードを追加router.beforeEach((to, _from, next) => {  const client = createIntlayerClient();  const metaLocale = to.meta.locale as Locales | undefined;  if (metaLocale) {    // ルートのメタに定義されたロケールを再利用    client.setLocale(metaLocale);    next();  } else {    // フォールバック: メタにロケールがない場合、おそらく一致しないルート    // オプション: 404を処理するか、デフォルトのロケールにリダイレクトする    client.setLocale(defaultLocale);    if (middleware.prefixDefault) {      next(`/${defaultLocale}${getPathWithoutLocale(to.path)}`);    } else {      next(getPathWithoutLocale(to.path));    }  }});

    ルート名はルーター内でルートを識別するために使用されます。すべてのルートで一意である必要があり、競合を避け、適切なナビゲーションとリンクを保証します。

    次に、main.jsファイルでルーターを登録します:

    src/main.ts
    import { createApp } from "vue";import App from "./App.vue";import { router } from "./router";import "./style.css";const app = createApp(App);// アプリにルーターを追加app.use(router);// アプリをマウントapp.mount("#app");

    次に、App.vue ファイルを更新して RouterView コンポーネントをレンダリングします。このコンポーネントは現在のルートにマッチしたコンポーネントを表示します。

    src/App.vue
    <script setup lang="ts">import LocaleSwitcher from "@components/LocaleSwitcher.vue";</script><template>  <nav>    <LocaleSwitcher />  </nav>  <RouterView /></template>

    同時に、intLayerMiddlewarePlugin を使用してアプリケーションにサーバーサイドルーティングを追加することもできます。このプラグインはURLに基づいて現在のロケールを自動的に検出し、適切なロケールクッキーを設定します。ロケールが指定されていない場合、プラグインはユーザーのブラウザの言語設定に基づいて最適なロケールを判定します。ロケールが検出されない場合は、デフォルトのロケールにリダイレクトします。

    vite.config.ts
    import { defineConfig } from "vite";import vue from "@vitejs/plugin-vue";import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [vue(), intlayerPlugin(), intLayerMiddlewarePlugin()],});

    (オプション)ステップ8: ロケール変更時にURLを変更する

    ユーザーが言語を変更したときにURLを自動的に更新するには、LocaleSwitcher コンポーネントを Vue Router を使うように変更できます。

    src/components/LocaleSwitcher.vue
    <template>  <div class="locale-switcher">    <select v-model="selectedLocale" @change="changeLocale">      <option v-for="loc in availableLocales" :key="loc" :value="loc">        {{ getLocaleName(loc) }}      </option>    </select>  </div></template><script setup lang="ts">import { ref, watch } from "vue";import { useRouter } from "vue-router";import { Locales, getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";// Vue Router を取得const router = useRouter();// ロケール情報と setLocale 関数を取得const { locale, availableLocales, setLocale } = useLocale({  onLocaleChange: (newLocale) => {    // 現在のルートを取得し、ローカライズされたURLを作成    const currentPath = router.currentRoute.value.fullPath;    const localizedPath = getLocalizedUrl(currentPath, newLocale);    // ページをリロードせずにローカライズされたルートへ遷移    router.push(localizedPath);  },});// 選択されたロケールを ref で追跡const selectedLocale = ref(locale.value);// 選択が変更されたときにロケールを更新するconst changeLocale = () => {  setLocale(selectedLocale.value);};// selectedLocaleをグローバルなロケールと同期させるwatch(  () => locale.value,  (newLocale) => {    selectedLocale.value = newLocale;  });</script>

    ヒント: SEOとアクセシビリティを向上させるために、ステップ10で示したように、ローカライズされたページへのリンクには <a href="/fr/home" hreflang="fr"> のようなタグを使用してください。これにより、検索エンジンは言語別のURLを正しく検出しインデックス化できます。SPAの動作を維持するためには、@click.preventでデフォルトのナビゲーションを防止し、useLocaleでロケールを変更し、Vue Routerを使ってプログラム的にナビゲートすることが可能です。

    html
    <ol class="divide-text/20 divide-y divide-dashed overflow-y-auto p-1">  <li>    <a      hreflang="x-default"      aria-label="英語に切り替え"      target="_self"      aria-current="page"      href="/doc/get-started"    >      <div>        <span dir="ltr" lang="en">English</span>        <span>英語</span>        <span>EN</span>      </div>    </a>  </li>  <li>    <a      hreflang="es"      aria-label="スペイン語に切り替え"      target="_self"      href="/es/doc/get-started"    >      <div>        <span dir="ltr" lang="es">Español</span>        <span>スペイン語</span>        <span>ES</span>      </div>    </a>  </li></ol>

    (オプション)ステップ9:HTMLの言語属性と方向属性を切り替える

    アプリケーションが複数の言語をサポートしている場合、<html>タグのlang属性とdir属性を現在のロケールに合わせて更新することが非常に重要です。これにより以下が保証されます:

    • アクセシビリティ: スクリーンリーダーや支援技術は、正しい lang 属性に依存してコンテンツを正確に発音し解釈します。
    • テキストレンダリング: dir(方向)属性は、テキストが適切な順序(例:英語は左から右、アラビア語やヘブライ語は右から左)で表示されることを保証し、読みやすさに不可欠です。
    • SEO: 検索エンジンは lang 属性を使用してページの言語を判別し、適切なローカライズされたコンテンツを検索結果に表示します。

    ロケールが変更された際にこれらの属性を動的に更新することで、すべての対応言語において一貫性がありアクセシブルなユーザー体験を保証します。

    src/composables/useI18nHTMLAttributes.ts
    import { watch } from "vue";import { useLocale } from "vue-intlayer";import { getHTMLTextDir } from "intlayer";/** * 現在のロケールに基づいてHTMLの<html>要素の`lang`および`dir`属性を更新するComposable。 * * @example * // App.vueまたはグローバルコンポーネント内で * import { useI18nHTMLAttributes } from './composables/useI18nHTMLAttributes' * * useI18nHTMLAttributes() */export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  // ロケールが変更されるたびにHTML属性を更新する  watch(    () => locale.value,    (newLocale) => {      if (!newLocale) return;      // 言語属性を更新する      document.documentElement.lang = newLocale;      // テキストの方向を設定する(ほとんどの言語はltr、アラビア語やヘブライ語などはrtl)      document.documentElement.dir = getHTMLTextDir(newLocale);    },    { immediate: true }  );};

    このコンポーザブルは、App.vue またはグローバルコンポーネントで使用します。

    src/App.vue
    <script setup lang="ts">import { useI18nHTMLAttributes } from "@composables/useI18nHTMLAttributes";// 現在のロケールに基づいてHTML属性を適用するuseI18nHTMLAttributes();</script><template>  <!-- アプリのテンプレート --></template>

    (オプション)ステップ10:ローカライズされたリンクコンポーネントの作成

    アプリケーションのナビゲーションが現在のロケールを尊重するようにするために、カスタムの Link コンポーネントを作成できます。このコンポーネントは内部のURLに自動的に現在の言語をプレフィックスとして付加します。例えば、フランス語を話すユーザーが「About」ページへのリンクをクリックすると、/about ではなく /fr/about にリダイレクトされます。

    この動作は以下の理由で有用です:

    • SEOとユーザーエクスペリエンス:ローカライズされたURLは、検索エンジンが言語別のページを正しくインデックスし、ユーザーに好みの言語でコンテンツを提供するのに役立ちます。
    • 一貫性:アプリケーション全体でローカライズされたリンクを使用することで、ナビゲーションが現在のロケール内に留まり、予期しない言語の切り替えを防ぎます。
    • 保守性: ローカリゼーションのロジックを単一のコンポーネントに集約することで、URLの管理が簡素化され、アプリケーションの成長に伴いコードベースの保守や拡張が容易になります。
    src/components/Link.vue
    <template>  <a :href="localizedHref" v-bind="$attrs">    <slot />  </a></template><script setup lang="ts">import { computed } from "vue";import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";const props = defineProps({  href: {    type: String,    required: true,  },});const { locale } = useLocale();// リンクが外部リンクかどうかをチェックconst isExternalLink = computed(() => /^https?:\/\//.test(props.href || ""));// 内部リンク用のローカライズされたhrefを作成const localizedHref = computed(() =>  isExternalLink.value ? props.href : getLocalizedUrl(props.href, locale.value));</script>

    Vue Routerで使用する場合は、ルーター専用のバージョンを作成します:

    src/components/RouterLink.vue
    <template>  <router-link :to="localizedTo" v-bind="$attrs">    <slot />  </router-link></template><script setup lang="ts">import { computed } from "vue";import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";const props = defineProps({  to: {    type: [String, Object],    required: true,  },});const { locale } = useLocale();// router-link用のローカライズされたtoプロパティを作成const localizedTo = computed(() => {  if (typeof props.to === "string") {    return getLocalizedUrl(props.to, locale.value);  } else {    // 'to'がオブジェクトの場合は、pathプロパティをローカライズします    return {      ...props.to,      path: getLocalizedUrl(props.to.path ?? "/", locale.value),    };  }});</script>

    これらのコンポーネントをアプリケーションで使用します:

    src/App.vue
    <template>  <div>    <!-- Vueルーター -->    <RouterLink to="/">ルート</RouterLink>    <RouterLink to="/home">ホーム</RouterLink>    <!-- その他 -->    <Link href="/">ルート</Link>    <Link href="/home">ホーム</Link>  </div></template><script setup lang="ts">import Link from "@components/Link.vue";import RouterLink from "@components/RouterLink.vue";</script>

    (オプション)ステップ11:Markdownのレンダリング

    Intlayerは、Vueアプリケーション内でMarkdownコンテンツを直接レンダリングすることをサポートしています。デフォルトでは、Markdownはプレーンテキストとして扱われます。MarkdownをリッチなHTMLに変換するには、Markdownパーサーであるmarkdown-itを統合できます。

    これは、翻訳にリスト、リンク、強調などのフォーマットされたコンテンツが含まれる場合に特に便利です。

    デフォルトではIntlayerはMarkdownを文字列としてレンダリングしますが、installIntlayerMarkdown関数を使ってMarkdownをHTMLにレンダリングする方法も提供しています。

    intlayerパッケージを使ってMarkdownコンテンツを宣言する方法については、markdownドキュメントを参照してください。

    ts
    import MarkdownIt from "markdown-it";import { createApp, h } from "vue";import { installIntlayer, installIntlayerMarkdown } from "vue-intlayer";const app = createApp(App);installIntlayer(app);const md = new MarkdownIt({  html: true, // HTMLタグを許可  linkify: true, // URLを自動リンク化  typographer: true, // スマートクォートやダッシュなどを有効化});// IntlayerにmarkdownをHTMLに変換する際にmd.render()を使うよう指示installIntlayerMarkdown(app, (markdown) => {  const html = md.render(markdown);  return h("div", { innerHTML: html });});

    登録が完了すると、コンポーネントベースの構文を使ってMarkdownコンテンツを直接表示できます:

    vue
    <template>  <div>    <myMarkdownContent />  </div></template><script setup lang="ts">import { useIntlayer } from "vue-intlayer";const { myMarkdownContent } = useIntlayer("my-component");</script>

    TypeScriptの設定

    Intlayerはモジュール拡張を利用して、TypeScriptの利点を活かし、コードベースをより強固にします。

    alt text

    alt text

    TypeScriptの設定に自動生成された型定義が含まれていることを確認してください。

    tsconfig.json
    {  // ... 既存のTypeScript設定  "include": [    // ... 既存のTypeScript設定    ".intlayer/**/*.ts", // 自動生成された型定義を含める  ],}

    Gitの設定

    Intlayerによって生成されたファイルは無視することを推奨します。これにより、それらのファイルをGitリポジトリにコミットするのを避けることができます。

    これを行うには、以下の指示を.gitignoreファイルに追加してください。

    plaintext
    # Intlayerによって生成されたファイルを無視する.intlayer

    VS Code拡張機能

    Intlayerでの開発体験を向上させるために、公式のIntlayer VS Code拡張機能をインストールできます。

    VS Codeマーケットプレイスからインストール

    この拡張機能は以下を提供します:

    • 翻訳キーのオートコンプリート
    • 欠落している翻訳のリアルタイムエラー検出
    • 翻訳されたコンテンツのインラインプレビュー
    • 翻訳を簡単に作成・更新できるクイックアクション

    拡張機能の使用方法の詳細については、Intlayer VS Code Extension ドキュメントを参照してください。


    さらに進むために

    さらに進むには、ビジュアルエディターを実装するか、CMSを使用してコンテンツを外部化することができます。


    ドキュメント履歴

    • 5.5.10 - 2025-06-29: 履歴の初期化

    このドキュメントを改善するアイデアがある場合は、GitHubでプルリクエストを送信することで自由に貢献してください。

    ドキュメントへのGitHubリンク
    Intlayerの今後のリリースに関する通知を受け取る