# General Translation Integrations: 快速入门
URL: https://generaltranslation.com/zh/docs/integrations/paraglide/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 记录每条 Paraglide JS 消息周围的源代码，并将其作为上下文一并发送去翻译。

`@generaltranslation/paraglide-js` 会找出应用中每一处使用 Paraglide JS 消息的位置，并保存其周围的代码。这样，像“Order”这样的消息在送去翻译时就会附带相关代码，由此可以判断它是按钮、标题、名词还是动词。

它只读取你的源文件，不会修改 Paraglide JS，也从不运行你的打包工具，因此无论应用采用何种方式构建，它都能正常工作。

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

你需要：

* Node.js 20 或更高版本。
* Paraglide JS 1、2 或 3，并且至少已编译过一次，以确保其输出目录存在。
* 以 inlang 消息格式 (`plugin.inlang.messageFormat`) 存储的消息，例如 `messages/en.json`。
* 一个使用 CLI 翻译上述消息文件的项目 (参见 [CLI 快速入门](/docs/cli/quickstart)) 。
* 如果组件不是 JavaScript、TypeScript 或 JSX，需要在应用中安装相应框架的语言工具 (参见[支持的文件格式](/docs/integrations/paraglide/reference/file-formats)) 。

## 快速入门 [#quickstart]

安装软件包并收集上下文，然后照常翻译即可。

### 1. 安装 `@generaltranslation/paraglide-js`

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install --save-dev @generaltranslation/paraglide-js
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add --dev @generaltranslation/paraglide-js
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add --dev @generaltranslation/paraglide-js
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add --save-dev @generaltranslation/paraglide-js
    ```
  </Tab>
</Tabs>

### 2. 收集上下文

在应用目录下运行 [`paraglide-context`](/docs/integrations/paraglide/reference/paraglide-context)。添加 `--verbose` 参数会输出找到的用法数量，以及所用的 Paraglide JS 输出目录。

```bash
npx paraglide-context --verbose
```

基础区域设置中的每个消息文件旁都会生成一个元数据文件。对于每条被使用的消息，该文件会按源文件列出其每处用法的上下文代码：

```json title="messages/en.metadata.json"
{
  "greeting": {
    "sourceCode": {
      "src/Header.tsx": [
        {
          "before": "import { m } from './paraglide/messages.js';\n…",
          "target": "  return <h1>{m.greeting({ username })}</h1>;",
          "after": "}\n…"
        }
      ]
    }
  }
}
```

<Callout type="info">
  警告会指明跳过了哪些内容以及如何修复，例如：无法解析的导入别名、缺失的语言工具，或未被识别为 Paraglide JS 输出的目录。 (参见[解析导入](/docs/integrations/paraglide/guides/resolving-imports)。) 
</Callout>

### 3. 翻译消息

运行 [`gt translate`](/docs/cli/reference/commands/translate)。CLI 会查找与各消息文件位于同一目录下的元数据文件，并将其作为[键级元数据](/docs/cli/reference/keyed-metadata)随消息一并发送。

```bash
npx gt translate
```

为了让上下文保持最新，请在每次翻译前重新收集：

```json title="package.json"
{
  "scripts": {
    "translate": "paraglide-context && gt translate"
  }
}
```

<Callout type="info">
  仅添加新的上下文不会触发消息的重新翻译。只有消息的源文本发生变化时，才会重新翻译该消息。
</Callout>

## Next steps

- /docs/integrations/paraglide/guides/resolving-imports
- /docs/integrations/paraglide/guides/adding-file-formats

## Sitemap

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