語言切換器與 RTL
語言切換器使用者介面
純 HTML
對於沒有使用框架的頁面,請載入 i18n.js 並將 data-locale-select 指向 <select>(或將 data-locale-list 指向應成為連結的元素)。該指令碼會從 ui-languages.json 填入控制項,就地切換地區設定,並設定 <html lang> 和 dir。請勿根據瀏覽器語言新增第二次重新導向。詳細資訊、標記和完整指令碼:純 HTML 應用程式。
對於每個地區設定產生一個 HTML 檔案的靜態網站,請使用 HTML 頁面 中產生的語言清單,而不是此執行階段。
使用 ui-languages.json 資訊清單來建立語言選擇器。ai-i18n-tools 匯出兩個顯示輔助程式 — 請參閱執行階段輔助程式 → 顯示輔助程式以取得簽章。
範例 LanguageSelect 元件(React)
import { useMemo } from 'react';
import { useTranslation } from 'react-i18next';
import {
getUILanguageLabel,
getUILanguageLabelNative,
type UiLanguageManifestRow,
} from 'ai-i18n-tools/runtime';
import uiLanguages from './locales/ui-languages.json';
import { loadLocale } from './i18n';
function LanguageSelect({
value,
onChange,
}: {
value: string;
onChange: (code: string) => void;
}) {
const { t, i18n } = useTranslation();
const options = useMemo(
() =>
(uiLanguages as UiLanguageManifestRow[]).map((lang) => ({
code: lang.code,
// Settings/content dropdowns: shows translated name when available
label: getUILanguageLabel(lang, t),
// Header globe menu: shows "English / Deutsch"-style label, no t() call
nativeLabel: getUILanguageLabelNative(lang),
})),
[t]
);
const handleChange = async (code: string) => {
await loadLocale(code);
await i18n.changeLanguage(code);
onChange(code);
};
return (
<select value={value} onChange={(e) => handleChange(e.target.value)}>
{options.map((row) => (
<option key={row.code} value={row.code}>
{row.label}
</option>
))}
</select>
);
}上述處理常式是在應用程式已顯示後才切換語言。請一併在首次繪製前還原已儲存的語系:啟動語系。
getUILanguageLabel(lang, t) — 當翻譯後顯示 t(englishName),或當兩者不同時顯示 englishName / t(englishName)。適用於設定畫面。
getUILanguageLabelNative(lang) — 顯示 englishName / label(每行沒有 t() 呼叫)。適用於您希望顯示原生名稱的標頭選單。
ui-languages.json manifest 是 "{ code, label, englishName, direction }" 項目的 JSON 陣列(direction 為 "ltr" 或 "rtl")。範例:
[
{ "code": "en-GB", "label": "English (UK)", "englishName": "English (UK)", "direction": "ltr" },
{ "code": "pt-BR", "label": "Português (BR)", "englishName": "Portuguese (BR)", "direction": "ltr" },
{ "code": "de", "label": "Deutsch", "englishName": "German", "direction": "ltr" },
{ "code": "fr", "label": "Français", "englishName": "French", "direction": "ltr" },
{ "code": "ar", "label": "العربية", "englishName": "Arabic", "direction": "rtl" }
]清單由 generate-ui-languages 或 extract 從 sourceLocale + targetLocales 與隨附的主目錄產生。它會寫入至 languagesManifestPath(省略時預設為 {ui.flatOutputDir}/ui-languages.json)。如果您在設定中變更了語言環境,請再次執行 generate-ui-languages 或 extract 以重新整理該檔案。
RTL 語言
ai-i18n-tools 匯出 getTextDirection(lng) 和 applyDirection(lng) — 請參閱執行階段輔助程式 → RTL 輔助程式。
import { getTextDirection, applyDirection } from 'ai-i18n-tools/runtime';
getTextDirection('ar') // 'rtl'
getTextDirection('en-GB') // 'ltr'
// Applied automatically via i18n.on('languageChanged', applyDirection) — see Wire i18nextapplyDirection 會設定 document.documentElement.dir (瀏覽器),或在 Node.js 中為無操作。傳遞一個可選的 element 引數以指定特定元素。在您的 i18n 啟動程序中連接它 — 連接 i18next。
對於可能包含 → 箭頭的字串,請為從右至左的版面配置翻轉它們:
import { flipUiArrowsForRtl } from 'ai-i18n-tools/runtime';
const { i18n } = useTranslation();
const isRtl = getTextDirection(i18n.language) === 'rtl';
const label = flipUiArrowsForRtl(t('Next → Step'), isRtl);