# General Translation React SDKs (gt-react, gt-next, gt-react-native): getTranslationsSnapshot
URL: https://generaltranslation.com/zh/docs/react/reference/functions/get-translations-snapshot.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 为 `<GTProvider>` 加载指定区域设置的翻译。getTranslationsSnapshot 的 API 参考。

`getTranslationsSnapshot` 函数会按 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 的 `translations` prop 所需的格式加载某个区域设置的翻译。请在初始化完成后调用它，以生成供 provider 同步使用的翻译快照。

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。*

在 `gt-next` 中，请配合 Pages Router 使用此函数。App Router 的 React Server Component 导出会抛出异常；其服务器端翻译 setup 由 `gt-next` 负责管理。

## 概览 [#overview]

[初始化](/docs/react/reference/config#initialization) `gt-react` 后，等待当前区域设置的 `getTranslationsSnapshot` 返回结果，并将其传递给 provider。

```tsx
const translations = await getTranslationsSnapshot(locale);
```

*注意：请在 [`initializeGT`](/docs/react/reference/config#initialize) 或 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 之后调用 `getTranslationsSnapshot`，因为这两个函数会创建它所使用的翻译缓存。*

## 工作原理 [#how-it-works]

`getTranslationsSnapshot` 会调用已配置的 [`loadTranslations`](/docs/react/reference/functions/load-translations) 函数，通过翻译缓存加载该区域设置的翻译，然后返回一个可序列化的翻译快照。将此翻译快照传递给 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 后，已翻译内容即可同步渲染，不会出现加载闪烁。

## 参数 [#parameters]

| 参数                  | 描述          | 类型       | 可选 | 默认值 |
| ------------------- | ----------- | -------- | -- | --- |
| [`locale`](#locale) | 要加载翻译的区域设置。 | `string` | 否  | —   |

### `locale` [#locale]

**类型** `string` · **必填**

要加载其翻译内容的区域设置，使用 BCP 47 代码表示。

## 返回 [#returns]

**类型** `Promise<Record<Locale, Record<Hash, Translation>>>`

一个 Promise，解析为该区域设置的翻译快照，其结构符合 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 的 `translations` prop 所需的格式。

## 错误 [#errors]

在开发环境中，如果 [`loadTranslations`](/docs/react/reference/functions/load-translations) 被 reject，`getTranslationsSnapshot` 会记录一条警告并 resolve 为 `{}`。失败的区域设置会被忽略，因此将该翻译快照传递给 provider 时不会写入空的 entry。

在生产环境中，翻译缓存会记录加载器报错并返回一个空的 catalog，因此翻译快照中会包含 `{ [locale]: {} }`。失败的加载不会写入发起请求的那个缓存，后续加载仍可重试；但如果把该翻译快照传给另一个 provider，则会在那里写入一个空的 catalog。

如果你的加载器捕获了错误并返回 `{}`，缓存会将这个空对象视为一次成功的加载，并将其保留到 `cacheExpiryTime` 过期为止。

## 示例 [#examples]

*示例从 `gt-react` 导入；请改为从所用框架的 package 导入。*

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

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

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

export async function loadRoot(request: Request) {
  const locale = parseLocale(request);
  return {
    locale,
    translations: await getTranslationsSnapshot(locale), // [!code highlight]
  };
}

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

## 注意事项 [#notes]

* 完成初始化后调用 `getTranslationsSnapshot`。
* 将其结果传给 [`<GTProvider>`](/docs/react/reference/components/gt-provider) 的 `translations` prop。

## Sitemap

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