日本語

简体中文
English

日本語

简体中文
English

国際化ドキュメント - 多言語サポートと設定 ​

概要 ​

このドキュメントは、VJSP Vue3フレームワークの国際化（i18n）サポートメカニズムについて詳しく説明します。多言語設定、言語切り替え、翻訳ファイル管理、および実際の開発での応用を含みます。

国際化アーキテクチャ ​

コア機能 ​

  • モジュール化翻訳管理: 保守と拡張を容易にするためにモジュール方式で翻訳ファイルを整理
  • 動的言語切り替え: ページのリフレッシュなしでランタイムでの動的言語切り替えをサポート
  • Element Plus統合: Element Plusコンポーネントライブラリとの深い統合によりUIコンポーネントの多言語一貫性を確保
  • タイプセーフ: タイプセーフな翻訳関数呼び出しを提供
  • 永続的ストレージ: 言語設定をローカルストレージに自動保存

技術スタック ​

  • Vue I18n v11: コア国際化ライブラリ
  • Element Plus国際化: UIコンポーネントライブラリの多言語サポート
  • Pinia状態管理: 言語状態の永続化
  • 動的インポート: オンデマンドでの言語パックローディングによるパフォーマンス最適化

設定メカニズム ​

言語設定 ​

プロジェクトは3つの言語環境をサポート：

  • 簡体字中国語 (zh-CN): デフォルト言語
  • 英語 (en): 国際化サポート
  • 日本語 (ja): 多言語拡張

言語パックマッピング ​

Element Plus言語パックとプロジェクト言語設定のマッピング：

  • zh-CN → Element Plus zh-cn
  • en → Element Plus en
  • ja → Element Plus ja

ストレージ設定 ​

言語設定はキー名langでlocalStorageを使用して永続的ストレージを行い、ユーザーの設定が異なるセッション間で一貫性を保つようにします。

実装メカニズム ​

初期化プロセス ​

  1. アプリケーション起動: localStorageからユーザーの言語設定を読み取り
  2. プラグイン初期化: Vue I18nインスタンスを設定
  3. 言語パックローディング: 対応する言語の翻訳ファイルを動的にインポート
  4. Element Plus設定: UIコンポーネントライブラリの言語パックを設定
  5. グローバル登録: 翻訳関数をグローバルプロパティとして登録

言語切り替えメカニズム ​

  1. 状態更新: Piniaストアでグローバル言語状態を更新
  2. DOM更新: HTMLページのlang属性を設定
  3. イベント通知: グローバル言語変更イベントをトリガー
  4. コンポーネント応答: 翻訳を使用する関連コンポーネントが自動的に再レンダリング

翻訳ファイルローディング ​

動的インポート方式を使用して翻訳ファイルをロードし、オンデマンドローディングとコード分割を実現：

  • 基本翻訳ファイル（commonモジュール）
  • システムモジュール翻訳ファイル（systemモジュール）
  • ビジネスモジュール翻訳ファイル（オンデマンドロード）

翻訳ファイル構造 ​

モジュール化組織 ​

翻訳ファイルは機能モジュールごとに整理され、各モジュールに独立した翻訳リソースを含む：

shell
src/locales/
├── common/           # 共通翻訳
│   ├── zh-CN.ts     # 中国語共通翻訳
│   ├── en.ts        # 英語共通翻訳
│   └── ja.ts        # 日本語共通翻訳
├── system/           # システムモジュール翻訳
│   ├── zh-CN.ts     # 中国語システム翻訳
│   ├── en.ts        # 英語システム翻訳
│   └── ja.ts        # 日本語システム翻訳
└── module/          # ビジネスモジュール翻訳

名前空間規約 ​

  • common: 共通操作、フォーム、検証などの基本翻訳
  • system: システム管理関連モジュールの翻訳
  • ビジネスモジュール名: 特定のビジネス機能の翻訳リソース

開発ガイド ​

コンポーネントでの翻訳使用 ​

コンポジションAPI使用 ​

useI18nフックを使用して翻訳関数を取得：

typescript
import { useI18n } from '@/hooks/web/useI18n'

const { t } = useI18n()

// 基本翻訳使用
const title = t('common.add')

// 名前空間付き翻訳
const userTitle = t('system.user.pageTitle')

オプションAPI使用 ​

グローバルプロパティを通じて翻訳関数にアクセス：

typescript
export default {
  computed: {
    title() {
      return this.$t('common.add')
    },
  },
}

ビジネスモジュール開発例（Productモジュール） ​

1. 翻訳ファイルの作成 ​

src/locales/module/product/ディレクトリに言語ファイルを作成：

zh-CN.ts

typescript
export default {
  product: {
    pageTitle: '产品管理',
    productName: '产品名称',
    productCode: '产品编码',
    price: '价格',
    status: '状态',
    addProduct: '新增产品',
    editProduct: '编辑产品',
    deleteProduct: '删除产品',
    deleteConfirm: '确认删除产品"{name}"吗？',
    addSuccess: '产品新增成功',
    updateSuccess: '产品更新成功',
    deleteSuccess: '产品删除成功',
  },
}

en.ts

typescript
export default {
  product: {
    pageTitle: 'Product Management',
    productName: 'Product Name',
    productCode: 'Product Code',
    price: 'Price',
    status: 'Status',
    addProduct: 'Add Product',
    editProduct: 'Edit Product',
    deleteProduct: 'Delete Product',
    deleteConfirm: 'Confirm delete product "{name}"?',
    addSuccess: 'Product added successfully',
    updateSuccess: 'Product updated successfully',
    deleteSuccess: 'Product deleted successfully',
  },
}

2. モジュール翻訳の登録 ​

src/plugins/vueI18n/index.tsにモジュール名を追加：

typescript
const otherModules: string[] = ['product']

3. コンポーネントでの使用 ​

vue
<template>
  <div>
    <h2>{{ t('product.pageTitle') }}</h2>
    <el-button @click="handleAdd">
      {{ t('product.addProduct') }}
    </el-button>
  </div>
</template>

<script setup lang="ts">
import { useI18n } from '@/hooks/web/useI18n'

const { t } = useI18n()

const handleAdd = () => {
  // 製品追加ロジック
}
</script>

言語切り替え機能 ​

機能ビュー説明 ​

プロジェクトは直感的な言語切り替えインターフェースを提供し、ユーザーは上部ナビゲーションバーの言語セレクターを通じてアプリケーション言語を素早く切り替えることができます。言語セレクターはドロップダウンメニュー形式を使用し、現在の言語名を表示し、サポートされているすべての言語のオプションリストを提供します。

ツールクラスファイルパス ​

言語切り替え機能には以下のコアファイルが関与：

  • 状態管理: src/stores/modules/locale.ts - 言語状態と設定管理
  • ユーティリティ関数: src/utils/i18n.ts - 言語切り替えとクエリ機能を提供
  • プラグイン設定: src/plugins/vueI18n/index.ts - 国際化プラグインのコア実装
  • コンポーネント統合: src/layout/components/Navbar.vue - 言語セレクターコンポーネントの位置

切り替えメカニズム ​

言語切り替えはイベント駆動メカニズムを使用。ユーザーが新しい言語を選択すると：

  1. 状態更新: Piniaストアを通じてグローバル言語状態を更新
  2. DOM同期: HTMLページのlang属性を自動的に更新
  3. コンポーネント応答: グローバル言語変更イベントをトリガーし、翻訳を使用するすべてのコンポーネントが自動的に再レンダリング
  4. 永続的ストレージ: ユーザーの言語設定がローカルストレージに自動保存され、次回の訪問時に一貫性を確保

切り替えプロセスはページのリフレッシュを必要とせず、スムーズなユーザー体験を提供しながら、Element Plusコンポーネントライブラリの言語パックが同期されることを保証します。

ベストプラクティス ​

翻訳キー命名規約 ​

  1. モジュールプレフィックス: モジュール名を名前空間プレフィックスとして使用
  2. 意味的命名: キー名はその意味を明確に表現するべき
  3. 一貫性: 同じ意味のテキストには同じ翻訳キーを使用

動的パラメータ処理 ​

Vue I18nのパラメータ補間機能を使用：

typescript
// 翻訳ファイル
deleteConfirm: 'Confirm delete "{name}"?'

// コンポーネントでの使用
const message = t('product.deleteConfirm', { name: productName })

複数形処理 ​

複数形を処理する必要があるテキストの場合：

typescript
// 翻訳ファイル
itemCount: '{count} item | {count} items'

// コンポーネントでの使用
const message = t('common.itemCount', { count: itemCount }, itemCount)

エラーハンドリング ​

  1. キーが見つからない場合の処理: デフォルトのフォールバックテキストを提供
  2. ロード失敗の処理: デフォルト言語への優雅な降格
  3. タイプセーフ: TypeScriptを使用して翻訳キーの正確性を確保

パフォーマンス最適化 ​

キャッシュ戦略 ​

  • ユーザー言語設定のローカルストレージ: localStorageを通じてユーザーが選択した言語設定を永続化
  • 重複設定の回避: 言語切り替え時に現在の言語状態をチェックし、不要な更新操作を回避

ビルド最適化 ​

  • 翻訳ファイルの圧縮: Viteビルド時にリソースファイルを自動圧縮
  • チャンキング戦略: ベンダーチャンキングによるローディングパフォーマンスの最適化

トラブルシューティング ​

一般的な問題 ​

  1. 翻訳キーが見つからない: キー名のスペルと名前空間を確認
  2. 言語切り替えが無効: 言語パックのロード成功を確認
  3. Element Plus言語の不一致: 言語パックマッピング設定を確認

デバッグのヒント ​

  1. Vue Devtoolsを使用して翻訳状態を確認
  2. ブラウザコンソールで言語パックローディングログを確認
  3. localStorageの言語設定を検証

拡張ガイド ​

新しい言語の追加 ​

  1. src/locales/の下に対応する言語ディレクトリを作成
  2. 言語パックマッピング設定を追加
  3. 言語セレクターサポートを更新
  4. 新しい言語機能をテスト

カスタム翻訳ローダー ​

loadModuleMessages関数を修正してカスタム翻訳ローディングロジックを実装し、リモートサーバーやCDNからの翻訳リソースのローディングをサポート。