# General Translation React SDKs (gt-react, gt-next, gt-react-native): 配置 General Translation
URL: https://generaltranslation.com/zh/docs/react/guides/configuring.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 如何初始化 General Translation、配置凭据，并通过 `<GTProvider>` 传递翻译。

服务器端渲染的 React 以及各框架集成都需要进行配置，并使用 [`GTProvider`](/docs/react/reference/components/gt-provider) 向组件提供翻译。React SPA 可直接通过 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 进行初始化；这部分设置请参阅 [React SPA Quickstart](/docs/react/react-spa-quickstart)。

*注意：`gt-react`、`gt-tanstack-start` 和 `gt-react-native` 不会自动读取 `gt.config.json`——你需要导入它，并将其中的字段传入初始化调用中。在 Next.js 中，[`withGTConfig`](/docs/react/nextjs/config) 插件会为你读取 `gt.config.json`。*

## 初始化库 [#initialize]

在首次渲染之前，先完成一次 General Translation 的配置。

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    在一个会同时在服务器端和客户端加载的模块中调用一次 [`initializeGT`](/docs/react/reference/config#initialize)。你的框架会解析请求的区域设置，并在服务器端渲染时提供对应的翻译。

    ```tsx title="src/routes/root.tsx"
    import { initializeGT } from 'gt-react';
    import gtConfig from '../../gt.config.json';

    const loadTranslations = (locale: string) =>
      import(`../_gt/${locale}.json`).then((m) => m.default);

    initializeGT({ ...gtConfig, loadTranslations });
    ```

    [`loadTranslations`](/docs/react/reference/functions/load-translations) 和 [`loadDictionary`](/docs/react/reference/functions/load-dictionary) 回调、凭据以及区域设置配置都应放在初始化调用中，而不是放在 [`GTProvider`](/docs/react/reference/components/gt-provider) 上。
  </Tab>

  <Tab value="Next.js">
    Next.js 不需要手动调用初始化。将 [`withGTConfig`](/docs/react/nextjs/config) 插件 添加到 `next.config.ts`；它会读取 `gt.config.json`，并在构建时和请求时接入翻译功能。

    ```ts title="next.config.ts"
    import { withGTConfig } from 'gt-next/config';

    const nextConfig = {};

    export default withGTConfig(nextConfig, {
      // 例如 `dictionary`、`loadTranslationsPath` 和区域设置 overrides 等选项
    });
    ```
  </Tab>

  <Tab value="TanStack Start">
    在服务器端和客户端启动时调用一次 [`initializeGT`](/docs/react/reference/config#initialize)，并展开传入你的配置。

    ```tsx
    import { initializeGT } from 'gt-tanstack-start';
    import gtConfig from '../gt.config.json';

    const loadTranslations = (locale: string) =>
      import(`./_gt/${locale}.json`).then((m) => m.default);

    initializeGT({ ...gtConfig, loadTranslations });
    ```

    注册 [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware)，然后在请求层级内使用来自 `gt-tanstack-start` 的 [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale)。启用 [`localeRouting`](/docs/react/reference/config#locale-routing) 后，middleware 会先从路径前缀解析区域设置，再检查 cookie 和 `Accept-Language` header。
  </Tab>

  <Tab value="React Native">
    在应用启动时调用一次 [`initializeGT`](/docs/react/reference/config#initialize)，并展开传入你的配置。

    ```tsx
    import { initializeGT } from 'gt-react-native';
    import gtConfig from '../gt.config.json';

    const loadTranslations = (locale: string) =>
      import(`./_gt/${locale}.json`).then((m) => m.default);

    initializeGT({ ...gtConfig, loadTranslations });
    ```
  </Tab>
</Tabs>

## 添加 provider [#provider]

使用 [`GTProvider`](/docs/react/reference/components/gt-provider#contracts) 包装你的应用，让组件能够读取翻译。

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    在服务器端加载当前生效区域设置的翻译，然后将这两个值传给 provider。具体使用哪个加载器 API 取决于你的框架。

    ```tsx title="src/routes/root.tsx"
    import { GTProvider, getTranslationsSnapshot, parseLocale } from 'gt-react';

    export async function loadRoot(request: Request) {
      const locale = parseLocale(request);
      return {
        locale,
        translations: await getTranslationsSnapshot(locale),
      };
    }

    export function Root({ locale, translations, children }) {
      return (
        <GTProvider locale={locale} translations={translations}>
          {children}
        </GTProvider>
      );
    }
    ```

    provider 还接受 [`region`](/docs/react/reference/components/gt-provider#region) 和 [`enableI18n`](/docs/react/reference/components/gt-provider#enable-i18n) (默认为 `true`) 。当翻译被禁用，或当前生效区域设置等于默认区域设置时，内容会以源语言渲染。
  </Tab>

  <Tab value="Next.js">
    用 [`<GTProvider>`](/docs/react/reference/components/gt-provider#contracts) 包装你的根布局。它会从插件中读取请求的区域设置和翻译，因此 App Router provider 只接受 `children`。

    ```tsx title="app/layout.tsx"
    import { GTProvider, useLocale } from 'gt-next';

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      const locale = useLocale();
      return (
        <html lang={locale}>
          <body>
            <GTProvider>{children}</GTProvider>
          </body>
        </html>
      );
    }
    ```
  </Tab>

  <Tab value="TanStack Start">
    传入当前生效的 [`locale`](/docs/react/reference/components/gt-provider#locale) 及其对应的 [`translations`](/docs/react/reference/components/gt-provider#translations)。两者均为必填。

    ```tsx
    import { GTProvider, getTranslationsSnapshot } from 'gt-tanstack-start';

    const translations = await getTranslationsSnapshot(locale);

    <GTProvider locale={locale} translations={translations}>
      <App />
    </GTProvider>;
    ```
  </Tab>

  <Tab value="React Native">
    用 [`<GTProvider>`](/docs/react/reference/components/gt-provider#contracts) 包装你的应用。它会自行加载当前生效区域设置的翻译，因此不接受 `translations` 属性；[`locale`](/docs/react/reference/components/gt-provider#locale) 为可选，默认使用已存储的或设备区域设置。

    ```tsx
    import { GTProvider } from 'gt-react-native';

    <GTProvider>
      <App />
    </GTProvider>;
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **v11 变更 (React) ：** `gt-react` 的 provider 不再通过属性接收 `config`、[`loadTranslations`](/docs/react/reference/functions/load-translations) 或凭据。这部分 setup 现在放在初始化调用中；provider 只接收解析后的 [`locale`](/docs/react/reference/components/gt-provider#locale) 和 [`translations`](/docs/react/reference/components/gt-provider#translations)。
</Callout>

有关 provider 和初始化的所有选项，请参阅 [Configuration 参考](/docs/react/reference/config)。

## 添加凭据 [#credentials]

翻译交付和开发功能都需要项目 ID 和 API 密钥，并通过环境变量进行设置。

<Tabs items={['React', 'Next.js', 'TanStack Start', 'React Native']}>
  <Tab value="React">
    按照你的框架对客户端环境变量的约定暴露项目 ID 和开发 API 密钥，然后将它们传给 [`initializeGT`](/docs/react/reference/config#initialize)。切勿暴露生产 API 密钥。
  </Tab>

  <Tab value="Next.js">
    在环境变量中设置它们；该插件会自动读取。`GT_API_KEY` (生产密钥) 用于服务器端，也会被 CI 中的 CLI 使用。只有必须传到浏览器的值才使用 `NEXT_PUBLIC_` 前缀。

    ```bash title=".env.local"
    GT_PROJECT_ID="..."
    GT_DEV_API_KEY="gtx-dev-..."
    ```
  </Tab>

  <Tab value="TanStack Start">
    通过 bundler 的公开环境变量设置它们，并将其传入初始化调用。

    ```bash title=".env (Vite)"
    VITE_GT_PROJECT_ID="..."
    VITE_GT_DEV_API_KEY="gtx-dev-..."
    ```
  </Tab>

  <Tab value="React Native">
    通过 bundler 的公开环境变量设置它们，并将其传入初始化调用。

    ```bash title=".env (Expo)"
    EXPO_PUBLIC_GT_PROJECT_ID="..."
    EXPO_PUBLIC_GT_DEV_API_KEY="gtx-dev-..."
    ```
  </Tab>
</Tabs>

*注意：客户端只能暴露开发 API 密钥。生产 API 密钥仅供 CI 中的 CLI 使用，绝不能下发到客户端。*

## 选择翻译的交付方式 [#delivery]

General Translation 会根据你的配置，以以下其中一种模式解析翻译。不同框架中的方式都相同：

* **本地文件：**提供 [`loadTranslations`](/docs/react/reference/functions/load-translations) 以导入打包后的 JSON。参见 [在本地存储翻译](/docs/react/guides/storing-translations)。
* **General Translation CDN：**提供 [`projectId`](/docs/react/reference/config#project-id) (不使用自定义加载器) ，即可在运行时从 GT 的 CDN 获取翻译。
* **自定义端点：**设置自定义 [`cacheUrl`](/docs/react/reference/config#cache-url)，从你自己的主机加载。

在开发环境中，提供 [`projectId`](/docs/react/reference/config#project-id) 和开发 API 密钥会启用按需翻译和 hot reload，因此你编写过程中新增的字符串会自动翻译。在生产环境中，翻译来自你预先生成的文件或 CDN。

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/storing-translations

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.