使用您最喜欢的AI助手总结文档,并引用此页面和AI提供商
版本历史
- "更新 Solid useIntlayer API 用法以直接访问属性"v8.9.02026/5/4
- "添加 init 命令"v7.5.92025/12/30
- "初始化历史"v5.5.102025/6/29
此页面的内容已使用 AI 翻译。
查看英文原文的最新版本如果您有改善此文档的想法,请随时通过在GitHub上提交拉取请求来贡献。
文档的 GitHub 链接复制文档 Markdown 到剪贴板
翻译您的 Expo and React Native 应用 | 国际化(i18n)
请参阅 GitHub 上的应用模板。
什么是 Intlayer?
Intlayer 是一个创新的开源国际化(i18n)库,简化了现代应用中的多语言支持。它适用于多种 JavaScript/TypeScript 环境,包括 React Native(通过 react-intlayer 包)。
使用 Intlayer,你可以:
- 通过声明式字典在组件级别轻松管理翻译。
- 通过自动生成的类型确保 TypeScript 支持。
- 动态本地化内容,包括UI 字符串(在 React Web 中,还可以本地化 HTML 元数据等)。
- 享受高级功能,如动态语言环境检测和切换。
第一步:安装依赖
在你的 React Native 项目中,安装以下包:
复制代码到剪贴板
npm install intlayer react-intlayernpm install --save-dev react-native-intlayernpx intlayer init包说明
intlayer
核心的国际化工具包,用于配置、词典内容、类型生成和命令行工具。react-intlayer
React 集成,提供上下文提供者和 React 钩子,供你在 React Native 中获取和切换语言环境。react-native-intlayer
React Native 集成,提供 Metro 插件,用于将 Intlayer 集成到 React Native 打包工具中。
第二步:创建 Intlayer 配置文件
在你的项目根目录(或任何方便的位置),创建一个 Intlayer 配置 文件。它可能看起来像这样:
复制代码到剪贴板
/**
* 如果 Locales 类型不可用,尝试在你的 tsconfig.json 中将 moduleResolution 设置为 "bundler"
*/
import { Locales, type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
internationalization: {
locales: [
Locales.ENGLISH,
Locales.FRENCH,
Locales.SPANISH,
// ... 添加你需要的其他语言环境
],
defaultLocale: Locales.ENGLISH,
},
};
export default config;在此配置中,您可以:
- 配置您的支持语言列表。
- 设置一个默认语言环境。
- 以后,您可以添加更高级的选项(例如,日志、自定义内容目录等)。
- 更多信息请参见Intlayer 配置文档。
第3步:添加 Metro 插件
Metro 是 React Native 的打包工具。它是通过 react-native init 命令创建的 React Native 项目的默认打包工具。要在 Metro 中使用 Intlayer,您需要将插件添加到您的 metro.config.js 文件中:
复制代码到剪贴板
const { getDefaultConfig } = require("expo/metro-config");const { configMetroIntlayer } = require("react-native-intlayer/metro");module.exports = (async () => { const defaultConfig = getDefaultConfig(__dirname); return await configMetroIntlayer(defaultConfig);})();第4步:添加 Intlayer 提供者
为了在您的应用程序中保持用户语言的同步,您需要使用来自 react-intlayer-native 的 IntlayerProvider 组件包裹您的根组件。
请确保使用来自react-native-intlayer而不是react-intlayer的提供者。来自react-native-intlayer的导出包含了 web API 的 polyfills。
复制代码到剪贴板
import { Stack } from "expo-router";
import { getLocales } from "expo-localization";
import { IntlayerProvider } from "react-native-intlayer";
import { type FC } from "react";
const getDeviceLocale = () => getLocales()[0]?.languageTag;
const RootLayout: FC = () => {
return (
<IntlayerProvider defaultLocale={getDeviceLocale()}>
<Stack>
为了在您的应用程序中保持用户语言的同步,您需要使用来自 `react-intlayer` 的 `IntlayerProvider` 组件包裹您的根组件。
此外,您需要在 `index.js` 文件中添加 `intlayerPolyfill` 函数,以确保 Intlayer 能够正常工作。
```tsx fileName="app/_layout.tsx" codeFormat="typescript"
import { Stack } from "expo-router";
import { getLocales } from "expo-localization";
import { IntlayerProvider } from "react-native-intlayer";
import { type FC } from "react";
const getDeviceLocale = () => getLocales()[0]?.languageTag;
const RootLayout: FC = () => {
return (
<IntlayerProvider defaultLocale={getDeviceLocale()}>
<Stack>
<Stack.Screen name="(tabs)" options={{ headerShown: false }} />
</Stack>
</IntlayerProvider>
);
};
export default RootLayout;第5步:声明您的内容
复制代码到剪贴板
```jsx fileName="app/_layout.cjx" codeFormat="commonjs"const { Stack } = require("expo-router");const { getLocales } = require("expo-localization");const { IntlayerProvider } = require("react-native-intlayer");// 获取设备的语言环境const getDeviceLocale = () => getLocales()[0]?.languageTag;const RootLayout = () => { return ( <IntlayerProvider defaultLocale={getDeviceLocale()}> <Stack> <Stack.Screen name="(tabs)" options={{ headerShown: false }} /> </Stack> </IntlayerProvider> );};module.exports = RootLayout;第5步:声明您的内容
在项目中的任意位置(通常在 src/ 目录下)创建内容声明文件,使用 Intlayer 支持的任何扩展名格式:
.content.json.content.ts.content.tsx.content.js.content.jsx.content.mjs.content.mjx.content.cjs.content.cjx- 等等。
示例(使用带有 React Native TSX 节点的 TypeScript):
复制代码到剪贴板
import { t, type Dictionary } from "intlayer";
import type { ReactNode } from "react";
/**
* 我们的 "app" 域的内容字典
*/
import { t, type Dictionary } from "intlayer";
const homeScreenContent = {
key: "home-screen",
content: {
title: t({
en: "Welcome!",
fr: "Bienvenue!",
es: "¡Bienvenido!",
}),
},
} satisfies Dictionary;
export default homeScreenContent;有关内容声明的详细信息,请参阅 Intlayer 内容文档。
第4步:在组件中使用 Intlayer
在子组件中使用 useIntlayer 钩子以获取本地化内容。
示例
复制代码到剪贴板
import { Image, StyleSheet, Platform } from "react-native";
import { useIntlayer } from "intlayer";
import { HelloWave } from "@/components/HelloWave";
import ParallaxScrollView from "@/components/ParallaxScrollView";
import { ThemedText } from "@/components/ThemedText";
import { ThemedView } from "@/components/ThemedView";
import { type FC } from "react";
const HomeScreen = (): FC => {
const { title, steps } = useIntlayer("home-screen");
return (
<ParallaxScrollView
headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}
headerImage={
<Image
source={require("@/assets/images/partial-react-logo.png")}
style={styles.reactLogo}
/>
}
>
<ThemedView style={styles.titleContainer}>
<ThemedText type="title">{title}</ThemedText>
<HelloWave />
</ThemedView>
</ParallaxScrollView>
);
};
const styles = StyleSheet.create({
titleContainer: {
flexDirection: "row", // 横向排列
alignItems: "center", // 垂直居中对齐
gap: 8, // 元素间距为8
},
});
export default HomeScreen;当在基于字符串的属性中使用content.someKey(例如按钮的title或Text组件的children)时,请调用content.someKey.value来获取实际的字符串。
如果您的应用程序已经存在,您可以结合使用 Intlayer 编译器 和 提取命令 在一秒钟内转换成干个组件。
(可选)步骤 5:更改应用程序语言环境
要在组件内部切换语言环境,可以使用 useLocale 钩子的 setLocale 方法:
复制代码到剪贴板
import { type FC } from "react";
import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
import { getLocaleName } from "intlayer";
import { useLocale } from "react-intlayer";
export const LocaleSwitcher: FC = () => {
const { setLocale, availableLocales } = useLocale();
return (
<View style={styles.container}>
{availableLocales.map((locale) => (
<TouchableOpacity
key={locale}
style={styles.button}
onPress={() => setLocale(locale)}
>
<Text style={styles.text}>{getLocaleName(locale)}</Text>
</TouchableOpacity>
))}
</View>
);
};
const styles = StyleSheet.create({
container: {
flexDirection: "row", // 容器内元素横向排列
justifyContent: "center", // 水平居中对齐
alignItems: "center", // 垂直居中对齐
gap: 8, // 元素间距为8
},
button: {
paddingVertical: 6, // 垂直内边距6
paddingHorizontal: 12, // 水平内边距12
borderRadius: 6, // 边角圆角半径6
backgroundColor: "#ddd", // 背景颜色为浅灰色
},
text: {
fontSize: 14, // 字体大小14
fontWeight: "500", // 字体粗细500
color: "#333", // 文字颜色深灰
},
});这会触发所有使用 Intlayer 内容的组件重新渲染,现在显示新语言环境的翻译内容。
详情请参见 useLocale 文档。
配置 TypeScript(如果您使用 TypeScript)
Intlayer 会在一个隐藏文件夹中(默认是 .intlayer)生成类型定义,以提升自动补全功能并捕获翻译错误:
复制代码到剪贴板
// tsconfig.json{ // ... 您现有的 TS 配置 "include": [ "src", // 您的源代码 ".intlayer/types/**/*.ts", // <-- 确保包含自动生成的类型 // ... 您已经包含的其他内容 ],}这使得以下功能成为可能:
- 自动补全 您的字典键。
- 类型检查,如果访问不存在的键或类型不匹配,会发出警告。
Git 配置
为了避免提交 Intlayer 自动生成的文件,请将以下内容添加到您的 .gitignore 文件中:
复制代码到剪贴板
# 忽略 Intlayer 生成的文件.intlayerVS Code 扩展
为了提升您使用 Intlayer 的开发体验,您可以安装官方的 Intlayer VS Code 扩展。
此扩展提供:
- 翻译键的自动补全。
- 缺失翻译的实时错误检测。
- 翻译内容的内联预览。
- 轻松创建和更新翻译的快速操作。
有关如何使用该扩展的更多详细信息,请参阅Intlayer VS Code 扩展文档。
深入了解
- 可视化编辑器:使用Intlayer 可视化编辑器来可视化管理翻译。
- CMS 集成:您还可以将词典内容外部化,并从 CMS 中获取。
- CLI 命令:探索 Intlayer CLI,用于执行诸如提取翻译或检查缺失键等任务。
享受通过 Intlayer 为您的 React Native 应用构建强大国际化支持的乐趣!