Local Loader

從本地檔案系統取得翻譯內容，支援多檔案、可嵌套的結構，並可使用多種格式。

Local Loader 需要能存取本地檔案系統。
若部署於純前端應用或託管平台（如 Vercel），請改用 Bundled 。

載入流程

Local Loader 會從 rootDir 開始，依語系收集翻譯檔案，
並可透過 namespaces 限制載入範圍，最終解析並組合為 LocaleMessages。

Local Loader ─▶ Collect files ─▶ Parse (readers) ─▶ LocaleMessages

翻譯內容組織方式

index.json
index.yaml
note.md
index.json
error.json
  • 每個語系對應一個資料夾
  • 在每個語系資料夾下，可建立巢狀的資料夾結構，並放置多個翻譯檔案。
  • 支援任意檔案格式，取決於 Loader 啟用時所注入的 readers 設定。

關於 readers 與擴充方式，詳見：Readers 。

Key 結構規則

Loader 會根據 資料夾結構 與 檔案名稱，推導每一筆翻譯對應的完整 Key 路徑。

  • 每一層資料夾名稱都會依序組合為 Key 的前綴，作為 Key 路徑中的一個節點。
messages/
└─ en/
   ├─ index.json
   │   └─ { text: "Hello" }     → Key: "text"
   └─ ui/
      └─ index.json
          └─ { text: "Hello" }  → Key: "ui.text"
  • 當檔案名稱不是 index 時，檔名本身也會被視為 Key 路徑中的一個節點。
messages/
└─ en/
   ├─ index.json
   │   └─ { text: "Hello" }    → Key: "text"
   └─ ui.json
       └─ { text: "Hello" }    → Key: "ui.text"

使用方式

Local Loader 透過 設定檔 啟用。

defineIntorConfig({
  loader: {
    mode: "local",
  },
});

使用 Local Loader 時，語系導航將觸發 full reload，以確保新語系的翻譯檔案能正確載入。

若同時為 client 提供 Loader，切換語系時將不再自動觸發 full reload。

defineIntorConfig({
  server: {
    loader: {
      mode: "local",
    },
  },
  client: {
    loader: {
      url: "https://public-cdn.com/messages",
    },
  },
});

如需在語系導航時自動觸發 full reload，可手動啟用 routing.forceFullReload。

Readers

readers 是 Local Loader 的擴充機制，用來支援不同翻譯檔案格式，並將其正規化為 MessageObject。

關於 reader 的介面以及實作方式，詳見：MessageReader

可解析的檔案格式由執行階段注入的 readers 決定，以下為注入示例：

await intor(intorConfig, {
  readers: {
    md: mdReader,
    yaml: yamlReader,
    // ...
  },
});
await getTranslator(intorConfig, {
  readers: {
    md: mdReader,
    yaml: yamlReader,
    // ...
  },
});

On this page