# General Translation Integrations: 用法检测
URL: https://generaltranslation.com/zh/docs/integrations/paraglide/reference/usage-detection.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 介绍如何选择源文件、解析导入语句以及查找 Paraglide JS 消息的用法。用法检测参考。

每次运行 [`paraglide-context`](/docs/integrations/paraglide/reference/paraglide-context) 或 [`collectContext`](/docs/integrations/paraglide/reference/collect-context) 时，都只会读取应用的源代码，而不会运行应用的打包工具。它支持 Paraglide JS 1、2 和 3，需要 Node.js 20 或更高版本。

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

| 步骤                            | 决定内容                         |
| ----------------------------- | ---------------------------- |
| [文件](#files)                  | 分析哪些源文件。                     |
| [导入语句](#imports)              | 哪些导入语句最终解析到 Paraglide JS 文件。 |
| [输出目录](#outdirs)              | 哪些目录存放 Paraglide JS 的输出。     |
| [inlang 项目](#inlang-projects) | 为哪些消息文件生成元数据文件。              |
| [用法](#usages)               | 每条消息在何处使用。                   |

## 文件 [#files]

分析范围为 [`include`](/docs/integrations/paraglide/reference/collect-context#include) 匹配的文件，并排除 [`exclude`](/docs/integrations/paraglide/reference/collect-context#exclude) 匹配的文件、`node_modules`、构建产物和框架输出，以及所有被 `.gitignore` 忽略的内容。如果 `include` 中列出了项目外的文件 (如 `../shared`) ，这些文件也会被分析。

无法解析的文件会被跳过，并输出一条警告。JavaScript、TypeScript 和 JSX 以外的格式，请参阅[支持的文件格式](/docs/integrations/paraglide/reference/file-formats)。

## 导入语句 [#imports]

导入语句从不按文本进行匹配。每条导入语句都会被解析，并沿着重新导出 (ESM 和 CommonJS) 逐层追踪，只有最终指向 Paraglide JS 文件时才会被计入。

其解析方式与应用的打包工具一致，但无需实际运行打包工具。别名依次来自以下来源：

1. [`alias`](/docs/integrations/paraglide/reference/collect-context#alias) 选项。
2. 找到的第一个 `vite.config.*`、`webpack.config.*` 或 `rspack.config.*`。Vite 配置由项目自身的 Vite 解析，因此插件别名 (如 SvelteKit 的 `$lib`) 和根目录路径 (`/src/a.js`) 均可正常使用。webpack 或 rspack 配置会被直接导入，因此若使用 TypeScript 配置文件，需要能够运行 TypeScript 的 Node.js 版本。此类配置中的 `name$` 和通配符 (`"@/*"`) 别名均可正常使用。
3. `tsconfig.json` 中的 `paths` 以及 `package.json` 中的 `imports`。

如果无法读取任何打包工具配置，未能解析的导入语句会在警告中列出，因为它们可能是未声明的别名 (参见[解析导入语句](/docs/integrations/paraglide/guides/resolving-imports)) 。

### 自动导入

未经导入直接使用的名称，会从 unplugin-auto-import、unplugin-vue-components 和 Nuxt 的 `.d.ts` 文件中读取。其他名称请通过 [`autoImports`](/docs/integrations/paraglide/reference/collect-context#auto-imports) 声明。

## 输出目录 [#outdirs]

系统会自动检测 Paraglide JS 的输出目录，因此在同一个应用中使用多个 Paraglide JS 项目时无需额外的初始化设置。如果某个目录包含的内容与已安装的 Paraglide JS 所生成的内容完全一致 (无论是磁盘上的文件还是虚拟模块) ，该目录即被识别为输出目录。对于 Paraglide JS 1，只要目录结构相同即可被识别。

看起来像输出目录但未通过检查的目录会被跳过，并给出警告。如仍需使用该目录，请将其列入 [`outdirs`](/docs/integrations/paraglide/reference/collect-context#outdirs)。如果未找到任何输出目录，系统会发出警告，提示无法记录任何用法。

## inlang 项目 [#inlang-projects]

每个输出目录都对应一个 inlang 项目，元数据会写入该项目中基础区域设置的消息文件。项目按以下顺序确定：

1. 输出目录的 `README.md` 中注明的编译来源项目。
2. [`root`](/docs/integrations/paraglide/reference/collect-context#root) 与 monorepo 根目录之间唯一的 `*.inlang` 目录。
3. 若存在多个此类目录，则选择定义了该输出目录中最多消息的那个。

设置 [`inlangProjects`](/docs/integrations/paraglide/reference/collect-context#inlang-projects) 后将不再执行上述查找。找不到对应项目的输出目录会产生警告，且不会为其消息生成元数据文件。

## 用法 [#usages]

借助 typescript-eslint 的作用域分析，可通过以下方式追踪值：

* 别名 (`const t = m`) 、解构和重新赋值
* 对象展开
* 函数参数及参数默认值
* 组件属性，包括跨模块传递的属性以及来自模板的属性
* 计算键 (`m["a"]`、`m[c ? "a" : "b"]`) 

满足以下任一情况时，消息即视为已使用：

| 用法         | 示例                |
| ---------- | ----------------- |
| 被调用        | `m.tos()`         |
| 通过其某个方法被调用 | `m.tos.parts()`   |
| 未调用但被引用    | `message={m.tos}` |

如果代码中使用了生成的目录里不存在的消息，这些用法会在警告中列出。

默认情况下，Paraglide JS 文件包括 `messages.js`、`messages/` 中的模块、`runtime.js`、`server.js`、`registry.js`，以及 Paraglide 的框架适配器软件包 (参见 [Targets](/docs/integrations/paraglide/reference/extension-api#targets)) 。

## 限制 [#limits]

* **别名：** 打包工具配置只提供其中的别名和 Vite 的根目录，不包括其插件的虚拟模块。不会读取 Next.js、Nuxt 和 Astro 的配置；它们的别名取自 `tsconfig.json`。
* **其他目标：** 运行时函数和适配器组件的用法会被分析，但不会被写入。只有消息才有可写入的键。
* **值流：** 追踪在返回值、React 上下文、`provide`/`inject`、数组以及后续才赋值的对象处终止。无条件重新赋值之后的读取只能看到新值。不对循环建模。
* **属性：** 属性会被追踪到 Svelte、Vue 和 Astro 组件中，但不会追踪到通过 `app.component()` 注册或通过 `<svelte:component this={X}>` 渲染的组件中。
* **计算键：** 可能取值超过 16 个的键会变为 `*`，不匹配任何单条消息。
* **CommonJS：** 不追踪模块顶层以下的导出。
* **损坏的 Astro 文件：** 未闭合的 `{` 之后，该元素的剩余部分会丢失。如果仅使用 `@astrojs/compiler` (Astro 6 及更早版本) ，则会丢失该行的剩余部分。

## Sitemap

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