こんにちは。コドモンの羽馬です。
現在、私たちは社内の有志メンバーで Vue 3への移行プロジェクトを進めています。
Vue 2 は公式サポートが2023年12月31日に終了しましたが、私たちは HeroDevs の延長サポート（NES）を利用し、セキュリティパッチや重要な修正を受けながら計画的な移行を進めています。
社内の多言語対応しているプロダクトでは Vue I18n を利用していますが、バージョンアップには多くの変更点があります。
そこで vue-i18n-bridge を採用し、既存のコードを活用しながら段階的に v9 への移行を進めることにしました。
この記事では、vue-i18n-bridge を利用した Vue I18n v9 への移行手順を紹介します。移行時に直面した課題とその解決方法についても解説します。
Vue I18n / vue-i18n-bridge とは
Vue I18n は Vue.js の国際化ライブラリで、多言語対応アプリケーションの開発を支援します。しかし、Vue 3 への移行に伴い、Vue I18n も大きな変更が必要になりました。
そこで登場したのが vue-i18n-bridge です。これは Vue I18n v8 (Vue 2 対応) から v9 (Vue 3 対応) への段階的な移行を可能にする橋渡しの役割（bridge）を担うライブラリです。
vue-i18n-bridge を使用することで、Vue 2 の環境でも Vue I18n v9 の機能を部分的に利用でき、将来的な移行が楽になります。
移行戦略
今回の移行では、以下の段階的アプローチを採用しました。
1. 現状把握と影響調査
現在利用している Vue I18n の機能を洗い出し、v9 での変更によって影響を受ける箇所を Issues にまとめました。
公式の移行ガイドを参考に、地道に影響範囲を洗い出す作業となり、一定の時間を要しました。
調査の結果、私たちのプロダクトは Options API を中心に構築されているため、必要な変更は比較的少ないことがわかりました。
2. vue-i18n-bridge の導入
vue-i18n-bridge を利用して、既存コードへの影響を最小限に抑えながら移行を進めました。
このライブラリを使用する前に、以下のパッケージをインストールしてください。
- vue-i18n: >= v8.26.1 < v9 vue-demi: >= v0.13.5 @vue/composition-api: >= v1.2.0 (Vue 2.6を使用する場合)
前提として、移行ガイドに記載されているとおり、vue-i18n v8.26.1以上が必要となるため、vue-i18nのアップデートも併せて実施しました。
import jaJP from '@/assets/lang/ja_JP.json' import enUS from '@/assets/lang/en_US.json' import VueI18n from 'vue-i18n' import { createI18n } from 'vue-i18n-bridge' Vue.use(VueI18n, { bridge: true }) // you must specify '{ bridge: true }' plugin option when install vue-i18n // `createI18n` options is almost same vue-i18n-next (vue-i18n@v9.x) API const i18n = createI18n({ locale: 'ja', messages: { en: enUS, ja: jaJP } }, VueI18n)
3. 段階的な移行
Options API をメインで利用しているため、大きな変更なく v9 へのアップデート準備を整えることができました。
将来的には Composition API への移行も視野に入れているため、書き換え可能な部分は少しずつ Composition API を利用する形で進めています。
移行時の制限事項
vue-i18n-bridge には以下の制限があり、完全な移行ではないことに注意が必要です。
Legacy API モードでの制限:
- 新しいメッセージフォーマット構文は使用できません（Composition API モードでのみ利用可能）
- 以下のコンポーネントは使用できません：
- Translation コンポーネント:
<i18n-t> - DateTime format コンポーネント:
<i18n-d> - Number format コンポーネント:
<i18n-n>
- Translation コンポーネント:
Composition API モードでの制限:
$t、$d、$nなどのグローバルスコープ API には$プレフィックスが付く
これらの制限により、v9 への完全移行時には追加の対応が必要な箇所は残りますが、大部分の移行を完了できたことは大きな成果でした。
詳細は Limitations を参照してください。
移行時にはまったポイント
Webpack での ES Module 認識エラー
移行作業中に遭遇した問題を以下に示します。
ERROR ./node_modules/vue-i18n-bridge/dist/vue-i18n-bridge.mjs 80:13-27 Can't import the named export 'CoreErrorCodes' from non EcmaScript module (only default export is available)
原因： vue-i18n-bridge.mjs から CoreErrorCodes をインポートする際にエラーが発生しました。モジュールがES Modules形式として認識されず、デフォルトエクスポートのみ利用可能となっていました。
これは、Webpack が node_modules 内にある .mjs ファイルを期待どおり ES Module として解釈・処理できていないことが原因でした。
解決策： Webpack の設定で、node_modules 内の .mjs ファイルを ES Module として扱うよう明示的なルールを追加することで解決しました。
vue.config.js への設定でも可能ですが、今回は webpack.config.js に以下の設定を追加しました。
// webpack.config.js module.exports = { module: { rules: [ { test: /\.mjs$/, include: /node_modules/, type: 'javascript/auto' } ] }, }
方法2: vue.config.js での設定（Vue CLI使用時）
module.exports = { configureWebpack: { module: { rules: [ { test: /\.mjs$/, include: /node_modules/, type: 'javascript/auto' } ] } } }
移行のメリット
vue-i18n-bridge を利用した移行により、以下のメリットを実感しています。
1. リスクの最小化
既存のコードをほぼそのまま利用できるため、大規模なリファクタリングに伴うバグのリスクを最小限に抑えられました。
2. 段階的な移行の実現
Vue 2 環境のまま vue-i18n v9 の機能を部分的に利用できるため、プロジェクト全体の Vue 3 移行と独立して進めることができました。
3. 最新機能への早期アクセス
vue-i18n v9 で追加された新機能（Composition API サポート、パフォーマンス向上など）を Vue 2 環境でも活用でき、開発効率の向上につながりました。
まとめ
vue-i18n-bridge を活用することで、Vue I18n v8 から v9 への移行を段階的に進めることができました。
特に Options API を中心に利用している既存プロジェクトでは、大きな変更なく移行準備を整えることができ、将来的な Vue 3 への移行がスムーズに進められそうです。
Webpack での ES Module 認識の問題など、いくつかの技術的な課題もありましたが、豊富なドキュメントのおかげで解決できました。引き続き、Vue 3 への移行を進めていきます。
