# General Translation Integrations: 使用 React 和 Node.js 实现 Databricks Apps 本地化
URL: https://generaltranslation.com/zh/docs/integrations/databricks/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 gt-react 和 gt-node 翻译基于 AppKit 构建的 Databricks App，从 React 界面到查询结果全面覆盖。

AppKit 是 Databricks 推出的 TypeScript SDK，用于构建 Databricks Apps。AppKit 应用由一个 Express 服务器和一个由 Vite 构建的 React 客户端组成，因此包含两层文本，分别在不同的位置进行翻译：

* **界面文本。** 即 `client/` 中的标题、按钮和标签。[`gt-react`](/docs/react/react-spa-quickstart) 会通过 CLI 预先翻译这些文本，并将译文随构建产物一同发布。
* **数据。** 即仅在运行时才产生的查询结果、Genie 回答和智能体输出。[`gt-node`](/docs/node/quickstart) 会在请求到达时于服务器端进行翻译。

两层读取的是同一个区域设置，因此选择西班牙语的访问者看到的标签和数据都是西班牙语。

## 开始之前 [#before-start]

你需要准备：

* 一个 AppKit 应用，例如通过 `databricks apps init` 创建的应用
* 一个[项目](/docs/platform/dashboard/get-started)，并安装 CLI 且已通过 [`gt login`](/docs/cli/reference/commands/login) 登录

## 快速入门 [#quickstart]

### 1. 安装软件包

在应用的根目录下运行以下命令：

```bash
npm i gt-react gt-node
npm i -D gt
```

### 2. 定义区域设置

在应用的根目录下创建 `gt.config.json`。AppKit 将客户端代码放在 `client/src/` 中，因此需要让 CLI 指向该目录：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "ja"],
  "src": ["client/src/**/*.{ts,tsx}"],
  "files": {
    "gt": {
      "output": "client/src/_gt/[locale].json"
    }
  }
}
```

客户端和服务器都会导入此文件，因此区域设置列表只需在一处维护。

### 3. 初始化客户端

为每个目标区域设置创建一个空的 JSON 文件，确保在生成译文之前导入语句就能正常解析：

```bash
mkdir -p client/src/_gt
echo '{}' > client/src/_gt/es.json
echo '{}' > client/src/_gt/ja.json
```

为翻译文件添加加载器：

```ts title="client/src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

创建一个引导文件，在应用渲染之前初始化 `gt-react`：

```ts title="client/src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../../gt.config.json';
import loadTranslations from './loadTranslations';

await initializeGTSPA({ ...gtConfig, loadTranslations });

await import('./main'); // 等翻译加载完成后再渲染应用
```

然后修改 `client/index.html`，使其指向这个新文件：

```html title="client/index.html"
<script type="module" src="/src/main.tsx"></script> <!-- [!code --] -->
<script type="module" src="/src/index.ts"></script> <!-- [!code ++] -->
```

 (参见[配置 Vite SPA](/docs/react/guides/spa/configuring-vite-spa)) 。

### 4. 翻译界面

用 [`<T>`](/docs/react/reference/components/t) 包裹界面文本，并添加 [`<LocaleSelector>`](/docs/react/reference/components/locale-selector)：

```tsx title="client/src/components/Header.tsx"
import { T, LocaleSelector } from 'gt-react';

export function Header() {
  return (
    <header>
      <T>
        <h1>Sales dashboard</h1>
      </T>
      <LocaleSelector />
    </header>
  );
}
```

在应用的根组件中渲染它：

```tsx title="client/src/App.tsx"
import { Header } from './components/Header';

export default function App() {
  return (
    <>
      <Header />
      {/* 应用的其他内容 */}
    </>
  );
}
```

访问者选择语言后，`gt-react` 会将其保存到 `generaltranslation.locale` cookie 中，并重新加载页面。在下一步中，服务器会读取同一个 cookie。

### 5. 在服务器翻译数据

初始化 `gt-node`，为每个请求绑定对应的区域设置，并使用 [`tx`](/docs/node/reference/functions/tx) 翻译运行时文本：

```ts title="server/server.ts"
import type { Request } from 'express';
import { createApp, server } from '@databricks/appkit';
import { initializeGT, withGT, getRequestLocale, tx } from 'gt-node';
import gtConfig from '../gt.config.json' with { type: 'json' };

initializeGT(gtConfig);

// 优先使用语言选择器中选定的语言，其次使用浏览器语言
function resolveLocale(req: Request) {
  const picked = req.headers.cookie?.match(/(?:^|;\s*)generaltranslation\.locale=([^;]+)/)?.[1];
  return picked ?? getRequestLocale(req);
}

createApp({
  plugins: [server()],
  onPluginsReady(appkit) {
    appkit.server.extend((app) => {
      app.use('/api', (req, _res, next) => withGT(resolveLocale(req), () => next()));

      app.get('/api/regions', async (_req, res) => {
        const rows = [{ region: 'North America', note: 'Revenue grew in every quarter' }]; // 替换为你的查询
        const translated = await Promise.all(
          rows.map(async (row) => ({
            ...row,
            note: await tx(row.note, { $context: 'Analyst note in a sales dashboard' }),
          }))
        );
        res.json(translated);
      });
    });
  },
}).catch(console.error);
```

保留应用中已注册的插件；只需添加 `onPluginsReady`，或扩展现有的 `onPluginsReady` 即可。不受支持的区域设置会回退到 `defaultLocale`。

### 6. 添加凭据

创建一个具有 **运行时翻译** 权限 (`project:translations:generate`) 的项目 API 密钥，然后将它和你的项目 ID 一起添加到 `.env` 中：

```bash
echo "GT_PROJECT_ID=<project-id>" >> .env
echo "GT_API_KEY=$(npx gt api-key create --project-id <project-id> --name 'Databricks app' --permission project:translations:generate)" >> .env
```

[`gt api-key create`](/docs/cli/reference/commands/api-key-create) 只会输出新生成的密钥，因此可以直接将其重定向写入该文件。AppKit 在开发环境中会加载 `.env`，CLI 也会读取该文件。

<Callout type="warn">
  **警告：** 切勿将 `.env` 提交到版本控制中，也不要在 `client/` 中导入这些值。`client/` 下的所有内容都会被打包发送到浏览器。
</Callout>

### 7. 生成译文并运行

将界面文本翻译为所有目标区域设置对应的语言：

```bash
npx gt translate
```

CLI 会生成 `client/src/_gt/es.json` 和 `client/src/_gt/ja.json`。每次界面文本有改动时，都需要重新运行该命令。

运行 `npm run dev` 启动应用，然后在语言选择器中选择 **español**。页面重新加载后，标题会切换为西班牙语，`/api/regions` 返回的备注也会变为西班牙语。

## 常见问题 [#faqs]

### 哪些文本由 gt-react 处理，哪些由 gt-node 处理？

代码中直接编写的文本 (例如标题和标签) 由 `gt-react` 处理。这类文本只需通过 CLI 翻译一次，因此不会产生任何运行时开销。来自数据的文本 (例如表格、Genie 或智能体的输出) 则在服务器上通过 [`tx`](/docs/node/reference/functions/tx) 处理，因为这些内容要等到请求执行时才能确定。 (参见[翻译数据](/docs/integrations/databricks/guides/translating-data)。)

### 我需要 Databricks 插件吗？

不需要。`gt-react` 和 `gt-node` 都是普通的 npm 软件包，AppKit 会像对待其他依赖项一样运行它们。

### 这与 Databricks 的 ai_translate 有何不同？

[`ai_translate`](https://docs.databricks.com/aws/en/sql/language-manual/functions/ai_translate) 是一个处于公共预览阶段的 SQL 函数，可将文本翻译为你在查询中传入的目标语言。它适合在 SQL 中翻译表数据，支持的语言以其文档所列为准。

而本方案则是根据每位访问者的语言来翻译整个应用。访问者的语言取自语言选择器或浏览器设置，`gt-react` 会预先翻译界面，`gt-node` 则在每次请求时将运行时内容翻译为同一语言。两者可以搭配使用：在 SQL 中用 `ai_translate` 翻译某一列，同时用 `gt-react` 和 `gt-node` 翻译应用。

## Next steps

- /docs/integrations/databricks/guides/translating-data
- /docs/integrations/databricks/guides/deploying

## Sitemap

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