paraglide-js

Paraglide JS

概述

Paraglide JS 是一个基于编译器的国际化库，可生成带类型的消息函数和运行时辅助工具。当项目需要配置 Paraglide、使用消息、检测区域设置、集成 SSR，或重构生成的 paraglide/ 输出时，请使用此技能。

适用场景

• 将 Paraglide JS 添加到新应用或现有应用中
• 更新区域设置策略顺序或自定义策略
• 使用 paraglideMiddleware() 接入 SSR 区域设置检测
• 将 Paraglide 集成到 TanStack Start
• 在 monorepo 中复用一个 project.inlang

不要将此技能用于一般文案撰写或翻译质量审查。它用于代码集成和运行时行为。

核心工作流

1. 确定应用类型：Vite 应用、SSR 应用、TanStack Start 应用或 monorepo。
2. 对于基于 Vite 的应用，优先使用 Vite 插件。
3. 在无法集成打包工具，或某个软件包需要显式编译脚本时，使用 CLI 编译。
4. 仅在 SSR/服务端请求流程中添加服务端中间件。
5. 将 project.inlang 和消息文件作为事实来源；将生成的 paraglide/ 输出视为构建产物。
6. 更改消息、区域设置、策略或输出设置后，重新编译。

经验法则

• 在 Vite 项目中，优先使用 paraglideVitePlugin()，而不是手动生成输出。
• 优先使用内置策略，再考虑添加自定义策略。
• 有意安排策略顺序。越靠前的策略优先级越高。
• 只使用一种 URL 重写的负责方。不要同时使用路由器级 URL 重写和由中间件驱动的 URL 本地化，除非已检查是否会出现重定向循环。
• 在 monorepo 中，默认采用“每个软件包单独编译”，除非所有使用方都能共享完全相同的策略和运行时。

参考指南

• 阅读 references/basics.md，了解设置、生成文件以及消息和运行时的用法。
• 阅读 references/strategies.md，了解策略排序和自定义策略。
• 阅读 references/tanstack-start.md，了解 TanStack Start 集成模式。
• 阅读 references/monorepo.md，了解跨软件包共享 project.inlang 的模式。

常见错误

• 直接编辑生成的 src/paraglide/* 文件，而不是修改源消息或配置
• 更改 messages/*.json 或 project.inlang/settings.json 后忘记重新编译
• 在仅客户端的 SPA 中添加 paraglideMiddleware()
• 将偏好策略放在 url 之前，却未考虑其重定向行为
• 同时使用 TanStack Router 重写和基于 URL 的中间件本地化，却未测试是否会出现循环

外部来源

• 官方文档：https://inlang.com/m/gerre34r/library-inlang-paraglideJs/
• Vite 指南：https://inlang.com/m/gerre34r/library-inlang-paraglideJs/vite
• Monorepo 指南：https://inlang.com/m/gerre34r/library-inlang-paraglideJs/monorepo
• 中间件指南：https://inlang.com/m/gerre34r/library-inlang-paraglideJs/middleware
• TanStack Router i18n 指南：https://tanstack.com/router/v1/docs/framework/react/guide/internationalization-i18n