@intlayer/docs 8.4.5 → 8.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/dist/cjs/generated/docs.entry.cjs +20 -0
  2. package/dist/cjs/generated/docs.entry.cjs.map +1 -1
  3. package/dist/esm/generated/docs.entry.mjs +20 -0
  4. package/dist/esm/generated/docs.entry.mjs.map +1 -1
  5. package/dist/types/generated/docs.entry.d.ts +1 -0
  6. package/dist/types/generated/docs.entry.d.ts.map +1 -1
  7. package/docs/ar/configuration.md +520 -722
  8. package/docs/ar/intlayer_with_storybook.md +521 -0
  9. package/docs/bn/configuration.md +922 -0
  10. package/docs/bn/intlayer_with_hono.md +428 -0
  11. package/docs/de/configuration.md +369 -743
  12. package/docs/de/intlayer_with_storybook.md +521 -0
  13. package/docs/en/configuration.md +181 -507
  14. package/docs/en/intlayer_with_storybook.md +521 -0
  15. package/docs/en-GB/configuration.md +456 -657
  16. package/docs/en-GB/intlayer_with_storybook.md +521 -0
  17. package/docs/es/configuration.md +379 -754
  18. package/docs/es/intlayer_with_storybook.md +521 -0
  19. package/docs/fr/configuration.md +376 -757
  20. package/docs/fr/intlayer_with_storybook.md +521 -0
  21. package/docs/hi/configuration.md +532 -728
  22. package/docs/hi/intlayer_with_storybook.md +521 -0
  23. package/docs/id/configuration.md +371 -684
  24. package/docs/id/intlayer_with_storybook.md +521 -0
  25. package/docs/it/configuration.md +397 -775
  26. package/docs/it/intlayer_with_storybook.md +521 -0
  27. package/docs/ja/configuration.md +525 -724
  28. package/docs/ja/intlayer_with_storybook.md +521 -0
  29. package/docs/ko/configuration.md +525 -724
  30. package/docs/ko/intlayer_with_storybook.md +521 -0
  31. package/docs/pl/configuration.md +430 -734
  32. package/docs/pl/intlayer_with_storybook.md +521 -0
  33. package/docs/pt/configuration.md +375 -746
  34. package/docs/pt/intlayer_with_storybook.md +521 -0
  35. package/docs/ru/configuration.md +532 -701
  36. package/docs/ru/intlayer_with_storybook.md +521 -0
  37. package/docs/tr/configuration.md +527 -719
  38. package/docs/tr/intlayer_with_storybook.md +521 -0
  39. package/docs/uk/configuration.md +425 -744
  40. package/docs/uk/intlayer_with_storybook.md +521 -0
  41. package/docs/ur/configuration.md +922 -0
  42. package/docs/ur/intlayer_with_hono.md +428 -0
  43. package/docs/vi/configuration.md +412 -753
  44. package/docs/vi/intlayer_with_storybook.md +521 -0
  45. package/docs/zh/configuration.md +521 -714
  46. package/docs/zh/intlayer_with_storybook.md +521 -0
  47. package/package.json +6 -6
  48. package/src/generated/docs.entry.ts +20 -0
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  createdAt: 2024-08-13
3
- updatedAt: 2026-03-12
4
- title: 配置
5
- description: 了解如何为您的应用程序配置 Intlayer。了解各种设置和选项,以根据您的需求自定义 Intlayer。
3
+ updatedAt: 2026-03-20
4
+ title: 配置 (Configuration)
5
+ description: 了解如何为您的应用程序配置 Intlayer。理解各种设置和选项,以根据您的需求自定义 Intlayer。
6
6
  keywords:
7
7
  - 配置
8
8
  - 设置
@@ -14,61 +14,88 @@ slugs:
14
14
  - concept
15
15
  - configuration
16
16
  history:
17
+ - version: 8.4.0
18
+ date: 2026-03-20
19
+ changes: 为 'compiler.output' 和 'dictionary.fill' 添加了按语言环境的对象表示法
17
20
  - version: 8.3.0
18
21
  date: 2026-03-11
19
22
  changes: 将 'baseDir' 从 'content' 配置移动到 'system' 配置
20
23
  - version: 8.2.0
21
- date: 2026-03-10
22
- changes: 更新编译器选项,增加 'output' 和 'noMetadata' 支持
24
+ date: 2026-03-09
25
+ changes: 更新了编译器 (compiler) 选项,添加了对 'output' 和 'noMetadata' 的支持
23
26
  - version: 8.1.7
24
27
  date: 2026-02-25
25
- changes: 更新编译器选项
28
+ changes: 更新了编译器选项
29
+ - version: 8.1.5
30
+ date: 2026-02-23
31
+ changes: 添加了编译器选项 'build-only' 和字典前缀
26
32
  - version: 8.0.6
27
33
  date: 2026-02-12
28
- changes: 新增对 Open Router, Alibaba, Amazon, Google Vertex Bedrock, Fireworks, Groq, Hugging Face, 以及 Together.ai 提供商的支持
34
+ changes: 添加了对 Open Router, Alibaba, Amazon, Google Vertex Bedrock, Fireworks, Groq, Hugging Face Together.ai 提供商的支持
29
35
  - version: 8.0.5
30
36
  date: 2026-02-06
31
- changes: 在 AI 配置中添加 `dataSerialization`
37
+ changes: 在 AI 配置中添加了 `dataSerialization`
38
+ - version: 8.0.0
39
+ date: 2026-01-24
40
+ changes: 将导入模式 `live` 重命名为 `fetch`,以更好地描述底层机制。
41
+ - version: 8.0.0
42
+ date: 2026-01-22
43
+ changes: 将构建配置 `importMode` 移动到 `dictionary` 配置。
32
44
  - version: 8.0.0
33
45
  date: 2026-01-22
34
- changes: importMode 构建配置移动到字典配置。
46
+ changes: 在路由配置中添加了 `rewrite` 选项
35
47
  - version: 8.0.0
36
48
  date: 2026-01-18
37
- changes: 将系统配置与内容配置分离。将内部路径移至 `system` 属性。添加 `codeDir` 以将内容文件与代码转换分离。
49
+ changes: 将系统配置与内容配置分离。将内部路径移动到 `system` 属性。添加了 `codeDir` 以分离内容文件和代码转换。
38
50
  - version: 8.0.0
39
51
  date: 2026-01-18
40
- changes: 添加字典选项 `location` 和 `schema`
52
+ changes: 添加了字典选项 `location` 和 `schema`
41
53
  - version: 7.5.1
42
54
  date: 2026-01-10
43
- changes: 添加对 JSON5 和 JSONC 文件格式的支持
55
+ changes: 添加了对 JSON5 和 JSONC 文件格式的支持
44
56
  - version: 7.5.0
45
57
  date: 2025-12-17
46
- changes: 添加 `buildMode` 选项
58
+ changes: 添加了 `buildMode` 选项
59
+ - version: 7.0.0
60
+ date: 2025-10-25
61
+ changes: 添加了 `dictionary` 配置
62
+ - version: 7.0.0
63
+ date: 2025-10-21
64
+ changes: 使用路由配置 `routing` 替换了 `middleware`
65
+ - version: 7.0.0
66
+ date: 2025-10-12
67
+ changes: 添加了 `formatCommand` 选项
68
+ - version: 6.2.0
69
+ date: 2025-10-12
70
+ changes: 更新了 `excludedPath` 选项
71
+ - version: 6.0.2
72
+ date: 2025-09-23
73
+ changes: 添加了 `outputFormat` 选项
47
74
  - version: 6.0.0
48
- date: 2025-09-16
49
- changes: 添加 `live` 导入模式
75
+ date: 2025-09-21
76
+ changes: 删除了 `dictionaryOutput` 字段和 `i18nextResourcesDir` 字段
50
77
  - version: 6.0.0
51
78
  date: 2025-09-16
52
- changes: 添加 `live` 导入模式
79
+ changes: 添加了 `live` 导入模式
53
80
  - version: 6.0.0
54
81
  date: 2025-09-04
55
- changes: `liveSync` 替换 `hotReload` 字段,并新增 `liveSyncPort` 和 `liveSyncURL` 字段
82
+ changes: 使用 `liveSync` 替换了 `hotReload` 字段,并添加了 `liveSyncPort` 和 `liveSyncURL` 字段
56
83
  - version: 5.6.1
57
84
  date: 2025-07-25
58
- changes: `importMode` 选项替换 `activateDynamicImport`
85
+ changes: 使用 `importMode` 选项替换了 `activateDynamicImport`
59
86
  - version: 5.6.0
60
87
  date: 2025-07-13
61
- changes: 默认的 contentDir 从 `['src']` 改为 `['.']`
88
+ changes: 将默认的 contentDir 从 `['src']` 更改为 `['.']`
62
89
  - version: 5.5.11
63
90
  date: 2025-06-29
64
- changes: 添加 `docs` 命令
91
+ changes: 添加了 `docs` 命令
65
92
  ---
66
93
 
67
94
  # Intlayer 配置文档
68
95
 
69
96
  ## 概述
70
97
 
71
- Intlayer 配置文件允许自定义插件的各个方面,例如国际化、中间件和内容处理。本文档详细描述了配置中的每个属性。
98
+ Intlayer 配置文件允许您自定义插件的各个方面,如国际化 (internationalization)、中间件和内容处理。本文档提供了配置中每个属性的深度说明。
72
99
 
73
100
  ---
74
101
 
@@ -78,9 +105,9 @@ Intlayer 配置文件允许自定义插件的各个方面,例如国际化、
78
105
 
79
106
  ---
80
107
 
81
- ## 配置文件支持
108
+ ## 支持的配置文件格式
82
109
 
83
- Intlayer 支持 JSONJSMJS TS 配置文件格式:
110
+ Intlayer 接受 JSON, JS, MJS, TS 等配置文件格式:
84
111
 
85
112
  - `intlayer.config.ts`
86
113
  - `intlayer.config.js`
@@ -93,7 +120,7 @@ Intlayer 支持 JSON、JS、MJS 和 TS 配置文件格式:
93
120
 
94
121
  ---
95
122
 
96
- ## 示例配置文件
123
+ ## 配置文件示例
97
124
 
98
125
  ````typescript fileName="intlayer.config.ts" codeFormat="typescript"
99
126
  import { Locales, type IntlayerConfig } from "intlayer";
@@ -101,108 +128,108 @@ import { nextjsRewrite } from "intlayer/routing";
101
128
  import { z } from "zod";
102
129
 
103
130
  /**
104
- * Example Intlayer configuration file showing all available options.
131
+ * 显示所有可用选项的 Intlayer 配置文件示例。
105
132
  */
106
133
  const config: IntlayerConfig = {
107
134
  /**
108
- * Configuration for internationalization settings.
135
+ * 国际化设置配置。
109
136
  */
110
137
  internationalization: {
111
138
  /**
112
- * List of supported locales in the application.
113
- * Default: [Locales.ENGLISH]
139
+ * 应用程序支持的语言环境 (locales) 列表。
140
+ * 默认值: [Locales.ENGLISH]
114
141
  */
115
142
  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
116
143
 
117
144
  /**
118
- * List of required locales that must be defined in every dictionary.
119
- * If empty, all locales are required in `strict` mode.
120
- * Default: []
145
+ * 每个字典中必须定义的必需语言环境列表。
146
+ * 如果为空,在 `strict` 模式下所有语言环境都是必需的。
147
+ * 默认值: []
121
148
  */
122
149
  requiredLocales: [Locales.ENGLISH],
123
150
 
124
151
  /**
125
- * Strictness level for internationalized content.
126
- * - "strict": Errors if any declared locale is missing or undeclared.
127
- * - "inclusive": Warnings if a declared locale is missing.
128
- * - "loose": Accepts any existing locale.
129
- * Default: "inclusive"
152
+ * 国际化内容的严格程度。
153
+ * - "strict": 如果任何声明的语言环境缺失或未声明,则报错。
154
+ * - "inclusive": 如果声明的语言环境缺失,则警告。
155
+ * - "loose": 接受任何现有的语言环境。
156
+ * 默认值: "inclusive"
130
157
  */
131
158
  strictMode: "inclusive",
132
159
 
133
160
  /**
134
- * Default locale used as a fallback if the requested locale is not found.
135
- * Default: Locales.ENGLISH
161
+ * 当请求的语言环境未找到时使用的默认语言环境。
162
+ * 默认值: Locales.ENGLISH
136
163
  */
137
164
  defaultLocale: Locales.ENGLISH,
138
165
  },
139
166
 
140
167
  /**
141
- * Settings that control dictionary operations and fallback behavior.
168
+ * 控制字典操作和回退行为的设置。
142
169
  */
143
170
  dictionary: {
144
171
  /**
145
- * Controls how dictionaries are imported.
146
- * - "static": Statically imported at build time.
147
- * - "dynamic": Dynamically imported using Suspense.
148
- * - "fetch": Fetched dynamically via the live sync API.
149
- * Default: "static"
172
+ * 控制字典的导入方式。
173
+ * - "static": 在构建时静态导入。
174
+ * - "dynamic": 使用 Suspense 动态导入。
175
+ * - "fetch": 通过 Live Sync API 动态获取。
176
+ * 默认值: "static"
150
177
  */
151
178
  importMode: "static",
152
179
 
153
180
  /**
154
- * Strategy for auto-filling missing translations using AI.
155
- * Can be a boolean or a path pattern to store filled content.
156
- * Default: true
181
+ * 使用 AI 自动填充缺失翻译的策略。
182
+ * 可以是布尔值或用于保存填充内容的路径模式。
183
+ * 默认值: true
157
184
  */
158
185
  fill: true,
159
186
 
160
187
  /**
161
- * Physical location of the dictionary files.
162
- * - "local": Stored in the local filesystem.
163
- * - "remote": Stored in the Intlayer CMS.
164
- * - "hybrid": Stored in the local filesystem and the Intlayer CMS.
165
- * - "plugin" (or any custom string): Provided by a plugin or a custom source.
166
- * Default: "local"
188
+ * 字典文件的物理位置。
189
+ * - "local": 存储在本地文件系统中。
190
+ * - "remote": 存储在 Intlayer CMS 中。
191
+ * - "hybrid": 同时存储在本地和 Intlayer CMS 中。
192
+ * - "plugin" (或任何自定义字符串): 由插件或自定义源提供。
193
+ * 默认值: "local"
167
194
  */
168
195
  location: "local",
169
196
 
170
197
  /**
171
- * Whether to automatically transform content (e.g., Markdown to HTML).
172
- * Default: false
198
+ * 内容是否应自动转换 (例如:Markdown HTML)
199
+ * 默认值: false
173
200
  */
174
201
  contentAutoTransformation: false,
175
202
  },
176
203
 
177
204
  /**
178
- * Routing and middleware configuration.
205
+ * 路由和中间件配置。
179
206
  */
180
207
  routing: {
181
208
  /**
182
- * Locale routing strategy.
183
- * - "prefix-no-default": Prefix all except the default locale (e.g., /dashboard, /fr/dashboard).
184
- * - "prefix-all": Prefix all locales (e.g., /en/dashboard, /fr/dashboard).
185
- * - "no-prefix": No locale in the URL.
186
- * - "search-params": Use ?locale=...
187
- * Default: "prefix-no-default"
209
+ * 语言环境路由策略。
210
+ * - "prefix-no-default": 为除默认语言环境以外的所有语言环境添加前缀 (例如:/dashboard, /fr/dashboard)
211
+ * - "prefix-all": 为所有语言环境添加前缀 (例如:/en/dashboard, /fr/dashboard)
212
+ * - "no-prefix": URL 中没有语言环境。
213
+ * - "search-params": 使用 ?locale=...
214
+ * 默认值: "prefix-no-default"
188
215
  */
189
216
  mode: "prefix-no-default",
190
217
 
191
218
  /**
192
- * Where to store the user's selected locale.
193
- * Options: 'cookie', 'localStorage', 'sessionStorage', 'header', or an array of these.
194
- * Default: ['cookie', 'header']
219
+ * 存储用户选择的语言环境的位置。
220
+ * 选项: 'cookie', 'localStorage', 'sessionStorage', 'header' 或它们的数组。
221
+ * 默认值: ['cookie', 'header']
195
222
  */
196
223
  storage: ["cookie", "header"],
197
224
 
198
225
  /**
199
- * Base path for the application URLs.
200
- * Default: ""
226
+ * 应用程序 URL 的基础路径。
227
+ * 默认值: ""
201
228
  */
202
229
  basePath: "",
203
230
 
204
231
  /**
205
- * Custom URL rewriting rules for locale-specific paths.
232
+ * 针对各语言环境特定路径的自定义 URL 重写规则。
206
233
  */
207
234
  rewrite: nextjsRewrite({
208
235
  "/[locale]/about": {
@@ -213,130 +240,130 @@ const config: IntlayerConfig = {
213
240
  },
214
241
 
215
242
  /**
216
- * Settings for finding and processing content files.
243
+ * 与内容文件查找和处理相关的设置。
217
244
  */
218
245
  content: {
219
246
  /**
220
- * File extensions to scan for dictionaries.
221
- * Default: ['.content.ts', '.content.js', '.content.json', etc.]
247
+ * 扫描字典的文件扩展名。
248
+ * 默认值: ['.content.ts', '.content.js', '.content.json' ]
222
249
  */
223
250
  fileExtensions: [".content.ts", ".content.js", ".content.json"],
224
251
 
225
252
  /**
226
- * Directories where .content files are located.
227
- * Default: ["."]
253
+ * .content 文件所在的目录。
254
+ * 默认值: ["."]
228
255
  */
229
256
  contentDir: ["src"],
230
257
 
231
258
  /**
232
- * Directories where source code is located.
233
- * Used for build optimization and code transformation.
234
- * Default: ["."]
259
+ * 源代码所在位置。
260
+ * 用于构建优化和代码转换。
261
+ * 默认值: ["."]
235
262
  */
236
263
  codeDir: ["src"],
237
264
 
238
265
  /**
239
- * Patterns to exclude from scanning.
240
- * Default: ['node_modules', '.intlayer', etc.]
266
+ * 扫描中排除的模式。
267
+ * 默认值: ['node_modules', '.intlayer' ]
241
268
  */
242
269
  excludedPath: ["node_modules"],
243
270
 
244
271
  /**
245
- * Whether to watch for changes and rebuild dictionaries in development.
246
- * Default: true in development
272
+ * 开发过程中是否监视更改并重新构建字典。
273
+ * 默认值: 开发环境下为 true
247
274
  */
248
275
  watch: true,
249
276
 
250
277
  /**
251
- * Command to format newly created / updated .content files.
278
+ * 用于格式化新创建/更新的 .content 文件的命令。
252
279
  */
253
280
  formatCommand: 'npx prettier --write "{{file}}"',
254
281
  },
255
282
 
256
283
  /**
257
- * Visual Editor configuration.
284
+ * 可视化编辑器 (Visual Editor) 配置。
258
285
  */
259
286
  editor: {
260
287
  /**
261
- * Whether the visual editor is enabled.
262
- * Default: false
288
+ * 是否启用可视化编辑器。
289
+ * 默认值: false
263
290
  */
264
291
  enabled: true,
265
292
 
266
293
  /**
267
- * URL of your application for origin validation.
268
- * Default: ""
294
+ * 应用程序的 URL,用于源验证 (origin validation)。
295
+ * 默认值: ""
269
296
  */
270
297
  applicationURL: "http://localhost:3000",
271
298
 
272
299
  /**
273
- * Port for the local editor server.
274
- * Default: 8000
300
+ * 本地编辑器服务器的端口。
301
+ * 默认值: 8000
275
302
  */
276
303
  port: 8000,
277
304
 
278
305
  /**
279
- * Public URL for the editor.
280
- * Default: "http://localhost:8000"
306
+ * 编辑器的公开 URL
307
+ * 默认值: "http://localhost:8000"
281
308
  */
282
309
  editorURL: "http://localhost:8000",
283
310
 
284
311
  /**
285
- * Intlayer CMS URL.
286
- * Default: "https://app.intlayer.org"
312
+ * Intlayer CMS URL
313
+ * 默认值: "https://app.intlayer.org"
287
314
  */
288
315
  cmsURL: "https://app.intlayer.org",
289
316
 
290
317
  /**
291
- * Backend API URL.
292
- * Default: "https://back.intlayer.org"
318
+ * 后端 API URL
319
+ * 默认值: "https://back.intlayer.org"
293
320
  */
294
321
  backendURL: "https://back.intlayer.org",
295
322
 
296
323
  /**
297
- * Whether to enable real-time content synchronization.
298
- * Default: false
324
+ * 是否启用实时内容同步。
325
+ * 默认值: false
299
326
  */
300
327
  liveSync: true,
301
328
  },
302
329
 
303
330
  /**
304
- * AI-powered translation and generation settings.
331
+ * 基于 AI 的翻译和构建设置。
305
332
  */
306
333
  ai: {
307
334
  /**
308
- * AI provider to use.
309
- * Options: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai'
310
- * Default: 'openai'
335
+ * 要使用的 AI 提供商。
336
+ * 选项: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai'
337
+ * 默认值: 'openai'
311
338
  */
312
339
  provider: "openai",
313
340
 
314
341
  /**
315
- * Model to use from the selected provider.
342
+ * 要使用的所选提供商的模型。
316
343
  */
317
344
  model: "gpt-4o",
318
345
 
319
346
  /**
320
- * Provider API key.
347
+ * 提供商 API 密钥。
321
348
  */
322
349
  apiKey: process.env.OPENAI_API_KEY,
323
350
 
324
351
  /**
325
- * Global context to guide the AI in generating translations.
352
+ * 全局上下文,用于指导 AI 生成翻译。
326
353
  */
327
- applicationContext: "This is a travel booking application.",
354
+ applicationContext: "这是一个旅游预订应用程序。",
328
355
 
329
356
  /**
330
- * Base URL for the AI API.
357
+ * AI API 的基础路径 URL。
331
358
  */
332
359
  baseURL: "http://localhost:3000",
333
360
 
334
361
  /**
335
- * 数据序列化
362
+ * 数据序列化 (Data Serialization)
336
363
  *
337
- * 选项:
338
- * - "json": 标准、可靠;使用更多 token
339
- * - "toon": 生成更少的 token,但不如 JSON 稳定。
364
+ * 选项:
365
+ * - "json": 默认设置,稳健;消耗更多 Token
366
+ * - "toon": 消耗 Token 较少,可能不如 JSON 一致。
340
367
  *
341
368
  * 默认值: "json"
342
369
  */
@@ -344,142 +371,142 @@ const config: IntlayerConfig = {
344
371
  },
345
372
 
346
373
  /**
347
- * Build and optimization settings.
374
+ * 构建和优化设置。
348
375
  */
349
376
  build: {
350
377
  /**
351
- * Build execution mode.
352
- * - "auto": Automatic build during app build.
353
- * - "manual": Requires explicit build command.
354
- * Default: "auto"
378
+ * 构建执行模式。
379
+ * - "auto": 在应用程序构建期间自动构建。
380
+ * - "manual": 需要明确的构建命令。
381
+ * 默认值: "auto"
355
382
  */
356
383
  mode: "auto",
357
384
 
358
385
  /**
359
- * Whether to optimize the final bundle by pruning unused dictionaries.
360
- * Default: true in production
386
+ * 是否通过删除未使用的字典来优化最终包。
387
+ * 默认值: 生产环境下为 true
361
388
  */
362
389
  optimize: true,
363
390
 
364
391
  /**
365
- * Output format for generated dictionary files.
366
- * Default: ['esm', 'cjs']
392
+ * 生成的字典文件的输出格式。
393
+ * 默认值: ['cjs', 'esm']
367
394
  */
368
- outputFormat: ["esm"],
395
+ outputFormat: ["cjs", "esm"],
369
396
 
370
397
  /**
371
- * Indicates if the build should check TypeScript types.
372
- * Default: false
398
+ * 指示构建是否应检查 TypeScript 类型。
399
+ * 默认值: false
373
400
  */
374
401
  checkTypes: false,
375
402
  },
376
403
 
377
404
  /**
378
- * Logger configuration.
405
+ * 日志记录器 (Logger) 配置。
379
406
  */
380
407
  log: {
381
408
  /**
382
- * Logging level.
383
- * - "default": Standard logging.
384
- * - "verbose": Detailed debug logging.
385
- * - "disabled": No logging.
386
- * Default: "default"
409
+ * 日志级别。
410
+ * - "default": 标准日志记录。
411
+ * - "verbose": 深入调试日志记录。
412
+ * - "disabled": 禁用日志记录。
413
+ * 默认值: "default"
387
414
  */
388
415
  mode: "default",
389
416
 
390
417
  /**
391
- * Prefix for all log messages.
392
- * Default: "[intlayer]"
418
+ * 所有日志消息的前缀。
419
+ * 默认值: "[intlayer]"
393
420
  */
394
421
  prefix: "[intlayer]",
395
422
  },
396
423
 
397
424
  /**
398
- * System configuration (Advanced use cases)
425
+ * 系统配置 (高级用途)
399
426
  */
400
427
  system: {
401
428
  /**
402
- * Directory for storing localization dictionaries.
429
+ * 存储本地化字典的目录。
403
430
  */
404
431
  dictionariesDir: ".intlayer/dictionary",
405
432
 
406
433
  /**
407
- * Directory for module augmentation.
434
+ * TypeScript 模块扩充 (module augmentation) 目录。
408
435
  */
409
436
  moduleAugmentationDir: ".intlayer/types",
410
437
 
411
438
  /**
412
- * Directory for storing unmerged dictionaries.
439
+ * 存储未合并字典的目录。
413
440
  */
414
441
  unmergedDictionariesDir: ".intlayer/unmerged_dictionary",
415
442
 
416
443
  /**
417
- * Directory for storing dictionary types.
444
+ * 存储字典类型的目录。
418
445
  */
419
446
  typesDir: ".intlayer/types",
420
447
 
421
448
  /**
422
- * Directory where main application files are stored.
449
+ * 存储主要应用程序文件的目录。
423
450
  */
424
451
  mainDir: ".intlayer/main",
425
452
 
426
453
  /**
427
- * Directory where the configuration files are stored.
454
+ * 存储配置文件的目录。
428
455
  */
429
456
  configDir: ".intlayer/config",
430
457
 
431
458
  /**
432
- * Directory where the cache files are stored.
459
+ * 存储缓存文件的目录。
433
460
  */
434
461
  cacheDir: ".intlayer/cache",
435
462
  },
436
463
 
437
464
  /**
438
- * Compiler configuration (Advanced use cases)
465
+ * 编译器配置 (高级用途)
439
466
  */
440
467
  compiler: {
441
468
  /**
442
- * 指示是否应启用编译器。
469
+ * 指示是否启用编译器。
443
470
  *
444
- * - false : 禁用编译器。
445
- * - true : 启用编译器。
446
- * - "build-only" : 在开发期间跳过编译器以加快启动速度。
471
+ * - false: 禁用编译器。
472
+ * - true: 启用编译器。
473
+ * - "build-only": 在开发期间跳过编译器,加速启动时间。
447
474
  *
448
- * 默认值 : false
475
+ * 默认值: false
449
476
  */
450
477
  enabled: true,
451
478
 
452
479
  /**
453
- * 定义输出文件路径。替换 `outputDir`。
480
+ * 定义输出文件的路径。替换 `outputDir`。
454
481
  *
455
- * - `./` 开头的路径相对于组件目录解析。
456
- * - `/` 开头的路径相对于项目根目录 (`baseDir`) 解析。
482
+ * - `./` 路径相对于组件目录解析。
483
+ * - `/` 路径相对于项目根目录 (`baseDir`) 解析。
457
484
  *
458
- * - 在路径中包含 `{{locale}}` 变量将启用按语言分离开的字典生成。
485
+ * - 在路径中包含 `{{locale}}` 变量将为每个语言创建单独的字典。
459
486
  *
460
- * 示例:
487
+ * 示例:
461
488
  * ```ts
462
489
  * {
463
490
  * // 在组件旁边创建多语言 .content.ts 文件
464
491
  * output: ({ fileName, extension }) => `./${fileName}${extension}`,
465
492
  *
466
- * // output: './{{fileName}}{{extension}}', // 使用字符串模板的等效写法
493
+ * // output: './{{fileName}}{{extension}}', // 使用模板字符串的等效方式
467
494
  * }
468
495
  * ```
469
496
  *
470
497
  * ```ts
471
498
  * {
472
- * // 在项目根目录下创建按语言集中的 JSON 文件
499
+ * // 在项目根目录为每个语言创建集中的 JSON
473
500
  * output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
474
501
  *
475
- * // output: '/locales/{{locale}}/{{key}}.content.json', // 使用字符串模板的等效写法
502
+ * // output: '/locales/{{locale}}/{{key}}.content.json', // 使用模板字符串的等效方式
476
503
  * }
477
504
  * ```
478
505
  *
479
- * 变量列表:
506
+ * 变量列表:
480
507
  * - `fileName`: 文件名。
481
508
  * - `key`: 内容键。
482
- * - `locale`: 内容语言。
509
+ * - `locale`: 内容语言环境。
483
510
  * - `extension`: 文件扩展名。
484
511
  * - `componentFileName`: 组件文件名。
485
512
  * - `componentExtension`: 组件文件扩展名。
@@ -490,24 +517,24 @@ const config: IntlayerConfig = {
490
517
  output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
491
518
 
492
519
  /**
493
- * 指示转换后是否应保存组件。
494
- * 这样,编译器只需运行一次即可转换应用程序,然后即可将其删除。
520
+ * 指示组件在转换后是否应保存。
521
+ * 这样,编译器可以只运行一次以转换应用程序,然后删除。
495
522
  */
496
523
  saveComponents: false,
497
524
 
498
525
  /**
499
- * 仅在生成的文件中插入内容。对于每种语言的 i18next 或 ICU MessageFormat JSON 输出非常有用。
526
+ * 仅在生成的文件中插入内容。对于 i18next 或 ICU MessageFormat 格式的每种语言 JSON 输出非常有用。
500
527
  */
501
528
  noMetadata: false,
502
529
 
503
530
  /**
504
531
  * 字典键前缀
505
532
  */
506
- dictionaryKeyPrefix: "", // 为所有字典键设置前缀
533
+ dictionaryKeyPrefix: "", // 为提取的字典键添加可选前缀
507
534
  },
508
535
 
509
536
  /**
510
- * Custom schemas to validate the dictionaries content.
537
+ * 验证字典内容的自定义架构 (Schemas)。
511
538
  */
512
539
  schemas: {
513
540
  "my-schema": z.object({
@@ -516,7 +543,7 @@ const config: IntlayerConfig = {
516
543
  },
517
544
 
518
545
  /**
519
- * Plugins configuration.
546
+ * 插件配置。
520
547
  */
521
548
  plugins: [],
522
549
  };
@@ -524,592 +551,372 @@ const config: IntlayerConfig = {
524
551
  export default config;
525
552
  ````
526
553
 
527
- ## 配置参考
554
+ ---
555
+
556
+ ## 配置参考 (Configuration Reference)
528
557
 
529
- 以下部分描述了 Intlayer 可用的各种配置设置。
558
+ 以下部分描述了 Intlayer 中可用的各种配置项。
530
559
 
531
560
  ---
532
561
 
533
- ### 国际化配置
534
-
535
- 定义与国际化相关的设置,包括可用的语言环境和应用的默认语言环境。
536
-
537
- #### 属性
538
-
539
- - **locales**:
540
- - _类型_:`string[]`
541
- - _默认值_:`['en']`
542
- - _描述_:应用中支持的语言环境列表。
543
- - _示例_:`['en', 'fr', 'es']`
544
-
545
- - **requiredLocales**:
546
- - _类型_:`string[]`
547
- - _默认值_:`[]`
548
- - _描述_:应用中必需的语言环境列表。
549
- - _示例_:`[]`
550
- - _注意_:如果为空,则在 `strict` 模式下所有语言环境都是必需的。
551
- - _注意_:确保必需的语言环境也在 `locales` 字段中定义。
552
- - **strictMode**:
553
- - _类型_:`string`
554
- - _默认值_:`inclusive`
555
- - _描述_:确保使用 TypeScript 强化国际化内容的实现。
556
- - _注意_:如果设置为 "strict",翻译函数 `t` 将要求每个声明的语言环境都必须定义。如果缺少某个语言环境,或者配置中未声明某个语言环境,将抛出错误。
557
- - _注意_:如果设置为 "inclusive",翻译函数 `t` 将要求每个声明的语言环境都必须定义。如果缺少某个语言环境,将发出警告。但如果配置中未声明某个语言环境但该语言环境存在,则接受。
558
- - _注意_: 如果设置为 "loose",翻译函数 `t` 将接受任何存在的语言环境。
559
-
560
- - **defaultLocale**:
561
- - _类型_: `string`
562
- - _默认值_: `'en'`
563
- - _描述_: 当请求的语言环境未找到时,使用的默认语言环境作为回退。
564
- - _示例_: `'en'`
565
- - _注意_: 用于在 URL、cookie 或请求头中未指定语言环境时确定语言环境。
562
+ ### 国际化配置 (Internationalization Configuration)
566
563
 
567
- ---
564
+ 定义与国际化相关的设置,包括可用的语言环境和应用程序的默认语言环境。
568
565
 
569
- ### 编辑器配置
570
-
571
- 定义与集成编辑器相关的设置,包括服务器端口和激活状态。
572
-
573
- #### 属性
574
-
575
- - **applicationURL**:
576
- - _类型_: `string`
577
- - _默认值_: `http://localhost:3000`
578
- - _描述_: 应用程序的 URL。用于出于安全原因限制编辑器的来源。
579
- - _示例_:
580
- - `'http://localhost:3000'`
581
- - `'https://example.com'`
582
- - `process.env.INTLAYER_EDITOR_URL`
583
- - _注意_: 应用程序的 URL。用于出于安全原因限制编辑器的来源。如果设置为 `'*'`,则编辑器可从任何来源访问。
584
-
585
- - **port**:
586
- - _类型_: `number`
587
- - _默认值_: `8000`
588
- - _描述_: 可视化编辑器服务器使用的端口。
589
-
590
- - **editorURL**:
591
- - _类型_: `string`
592
- - _默认值_: `'http://localhost:8000'`
593
- - _描述_: 编辑器服务器的 URL。用于出于安全原因限制编辑器的来源。
594
- - `'http://localhost:3000'`
595
- - `'https://example.com'`
596
- - `process.env.INTLAYER_EDITOR_URL`
597
- - _注意_:应用程序访问的编辑器服务器的 URL。用于限制可以与应用程序交互的来源以确保安全。如果设置为 `'*'`,编辑器可以从任何来源访问。如果端口更改或编辑器托管在不同域名上,应设置此项。
598
-
599
- - **cmsURL**:
600
- - _类型_:`string`
601
- - _默认值_:`'https://intlayer.org'`
602
- - _描述_:Intlayer CMS 的 URL。
603
- - _示例_:`'https://intlayer.org'`
604
- - _注意_:Intlayer CMS 的 URL。
605
-
606
- - **backendURL**:
607
- - _类型_:`string`
608
- - _默认值_:`https://back.intlayer.org`
609
- - _描述_:后端服务器的 URL。
610
- - _示例_:`http://localhost:4000`
611
-
612
- - **enabled**:
613
- - _类型_:`boolean`
614
- - _默认值_:`true`
615
- - _描述_:指示应用程序是否与可视化编辑器交互。
616
- - _示例_:`process.env.NODE_ENV !== 'production'`
617
- - _注意_:如果为 true,编辑器将能够与应用程序交互。如果为 false,编辑器将无法与应用程序交互。无论如何,编辑器只能由可视化编辑器启用。在特定环境中禁用编辑器是一种加强安全性的方式。
618
-
619
- - **clientId**:
620
- - _类型_:`string` | `undefined`
621
- - _默认值_:`undefined`
622
- - _描述_: clientId 和 clientSecret 允许 intlayer 包使用 oAuth2 认证与后端进行身份验证。访问令牌用于验证与项目相关的用户。要获取访问令牌,请访问 https://app.intlayer.org/project 并创建一个账户。
623
- - _示例_: `true`
624
- - _注意_: 重要提示:clientId 和 clientSecret 应保持机密,不得公开共享。请确保将它们保存在安全的位置,例如环境变量中。
625
-
626
- - **clientSecret**:
627
- - _类型_: `string` | `undefined`
628
- - _默认值_: `undefined`
629
- - _描述_: clientId 和 clientSecret 允许 intlayer 包使用 oAuth2 认证与后端进行身份验证。访问令牌用于验证与项目相关的用户。要获取访问令牌,请访问 https://app.intlayer.org/project 并创建一个账户。
630
- - _示例_: `true`
631
- - _注意_: 重要提示:clientId 和 clientSecret 应保持机密,不得公开共享。请确保将它们保存在安全的位置,例如环境变量中。
632
-
633
- - **dictionaryPriorityStrategy**:
634
- - _类型_: `string`
635
- - _默认值_: `'local_first'`
636
- - _描述_: 当本地和远程词典同时存在时,优先使用词典的策略。如果设置为 `'distant_first'`,应用程序将优先使用远程词典而非本地词典。如果设置为 `'local_first'`,应用程序将优先使用本地词典而非远程词典。
637
- - _示例_: `'distant_first'`
638
-
639
- - **liveSync**:
640
- - _类型_: `boolean`
641
- - _默认值_: `false`
642
- - _描述_: 指示当检测到 CMS / 可视化编辑器 / 后端内容发生变化时,应用服务器是否应热重载应用内容。
643
- - _示例_: `true`
644
- - _备注_: 例如,当添加或更新新的词典时,应用程序会更新页面中显示的内容。
645
- - _注意_: 实时同步需要将应用内容外部化到另一个服务器。这意味着它可能会稍微影响应用的性能。为限制这种影响,我们建议将应用和实时同步服务器托管在同一台机器上。此外,实时同步与 `optimize` 的组合可能会对实时同步服务器产生大量请求。根据您的基础设施,我们建议测试这两种选项及其组合。
646
-
647
- - **liveSyncPort**:
648
- - _类型_: `number`
649
- - _默认值_: `4000`
650
- - _描述_: 实时同步服务器的端口。
651
- - _示例_: `4000`
652
- - _注意_: 实时同步服务器的端口。
653
-
654
- - **liveSyncURL**:
655
- - _类型_: `string`
656
- - _默认值_: `'http://localhost:{liveSyncPort}'`
657
- - _描述_: 实时同步服务器的 URL。
658
- - _示例_: `'https://example.com'`
659
- - _备注_: 默认指向 localhost,但在远程实时同步服务器的情况下可以更改为任何 URL。
660
-
661
- ### 中间件配置
662
-
663
- 控制中间件行为的设置,包括应用如何处理 cookie、头信息以及用于区域管理的 URL 前缀。
664
-
665
- #### 属性
666
-
667
- - **headerName**:
668
- - _类型_: `string`
669
- - _默认值_: `'x-intlayer-locale'`
670
- - _描述_: 用于确定区域的 HTTP 头名称。
671
- - _示例_: `'x-custom-locale'`
672
- - _备注_: 这对于基于 API 的区域确定非常有用。
673
-
674
- - **cookieName**:
675
- - _类型_: `string`
676
- - _默认值_: `'intlayer-locale'`
677
- - _描述_: 用于存储区域的 cookie 名称。
678
- - _示例_: `'custom-locale'`
679
- - _说明_: 用于在会话之间保持语言环境。
680
-
681
- - **prefixDefault**:
682
- - _类型_: `boolean`
683
- - _默认值_: `false`
684
- - _说明_: 是否在 URL 中包含默认语言环境。
685
- - _示例_: `true`
686
- - _说明_:
687
- - 如果为 `true` 且 `defaultLocale = 'en'`:路径为 `/en/dashboard` 或 `/fr/dashboard`
688
- - 如果为 `false` 且 `defaultLocale = 'en'`:路径为 `/dashboard` 或 `/fr/dashboard`
689
-
690
- - **basePath**:
691
- - _类型_: `string`
692
- - _默认值_: `''`
693
- - _说明_: 应用程序 URL 的基础路径。
694
- - _示例_: `'/my-app'`
695
- - _说明_:
696
- - 如果应用托管在 `https://example.com/my-app`
697
- - 基础路径为 `'/my-app'`
698
- - URL 将是 `https://example.com/my-app/en`
699
- - 如果未设置基础路径,URL 将是 `https://example.com/en`
700
-
701
- - **rewrite**:
702
- - _类型_: `Record<string, StrictModeLocaleMap<string>>`
703
- - _默认值_: `undefined`
704
- - _说明_: 自定义 URL 重写规则,用于覆盖特定路径的默认路由模式。允许定义与标准路由行为不同的特定语言路径。支持使用 `[param]` 语法的动态路由参数。
705
- - _示例_:
706
- ```typescript
707
- routing: {
708
- mode: "prefix-no-default", // 回退策略
709
- rewrite: nextjsRewrite({
710
- "/[locale]/about": {
711
- en: "/[locale]/about",
712
- fr: "/[locale]/a-propos",
713
- },
714
- "/[locale]/product/[slug]": {
715
- en: "/[locale]/product/[slug]",
716
- fr: "/[locale]/produit/[slug]",
717
- },
718
- "/[locale]/blog/[category]/[id]": {
719
- en: "/[locale]/blog/[category]/[id]",
720
- fr: "/[locale]/journal/[category]/[id]",
721
- },
722
- }),
723
- }
724
- ```
725
- - _说明_: 重写规则优先于默认的 `mode` 行为。如果路径匹配重写规则,将使用重写配置中的本地化路径,而不是标准语言前缀。
726
- - _说明_: 支持使用方括号表示法的动态路由参数(例如 `[slug]`、`[id]`)。参数值会自动从 URL 中提取并插入到重写的路径中。
727
- - _说明_: 适用于 Next.js 和 Vite 应用程序。中间件/代理会自动重写传入的请求以匹配内部路由结构。
728
- - _说明_: 使用 `getLocalizedUrl()` 生成 URL 时,如果重写规则与提供的路径匹配,将自动应用这些规则。
729
- - _参考_: 有关更多信息,请参阅 [自定义 URL 重写](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/custom_url_rewrites.md)。
730
-
731
- - **serverSetCookie**:
732
- - _类型_:`string`
733
- - _默认值_:`'always'`
734
- - _描述_:服务器端设置语言环境 Cookie 的规则。
735
- - _选项_:`'always'`,`'never'`
736
- - _示例_:`'never'`
737
- - _说明_:控制是否在每次请求时设置语言环境 Cookie,或者从不设置。
738
-
739
- - **noPrefix**:
740
- - _类型_:`boolean`
741
- - _默认值_:`false`
742
- - _描述_:是否在 URL 中省略语言环境前缀。
743
- - _示例_:`true`
744
- - _说明_:
745
- - 如果为 `true`:URL 中无前缀
746
- - 如果为 `false`:URL 中有前缀
747
- - 以 `basePath = '/my-app'` 为例:
748
- - 如果 `noPrefix = false`:URL 将是 `https://example.com/my-app/en`
749
- - 如果 `noPrefix = true`:URL 将是 `https://example.com`
566
+ | 字段 | 类型 | 说明 | 示例 | 备注 |
567
+ | ----------------- | ---------- | --------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
568
+ | `locales` | `string[]` | 应用程序支持的语言环境列表。默认值: `[Locales.ENGLISH]` | `['en', 'fr', 'es']` | |
569
+ | `requiredLocales` | `string[]` | 应用程序中必需的语言环境列表。默认值: `[]` | `[]` | 如果为空,在 `strict` 模式下所有语言环境都是必需的。请确保必需的语言环境也在 `locales` 字段中定义。 |
570
+ | `strictMode` | `string` | 确保使用 TypeScript 稳健地实现国际化内容。默认值: `inclusive` | | 如果为 `"strict"`: `t` 函数要求定义每个声明的语言环境 — 如果有任何缺失或未声明,则抛出错误。如果为 `"inclusive"`: 对缺失的语言环境进行警告,但接受现有的未声明语言环境。如果为 `"loose"`: 接受任何现有的语言环境。 |
571
+ | `defaultLocale` | `string` | 当请求的语言环境未找到时使用的默认语言环境。默认值: `Locales.ENGLISH` | `'en'` | 当 URL、Cookie 或 Header 中未指定语言环境时,用于确定语言环境。 |
750
572
 
751
573
  ---
752
574
 
753
- ### 内容配置
754
-
755
- 与应用内内容处理相关的设置,包括目录名称、文件扩展名及派生配置。
756
-
757
- #### 属性
758
-
759
- - **autoFill**:
760
- - _类型_:`boolean | string | FilePathPattern | { [key in Locales]?: string }`
761
- - _默认值_:`undefined`
762
- - _描述_:指示内容应如何使用 AI 自动填充。可以在 `intlayer.config.ts` 文件中全局声明。
763
- - _示例_:true
764
- - _示例_:'./{{fileName}}.content.json'
765
- - _示例_:{ fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }
766
- - _备注_:自动填充配置。它可以是:
767
- - boolean:为所有语言启用自动填充
768
- - string:单个文件路径或带变量的模板路径
769
- - object:每个语言的文件路径
770
-
771
- - **watch**:
772
- - _类型_:`boolean`
773
- - _默认值_:`process.env.NODE_ENV === 'development'`
774
- - _描述_:指示 Intlayer 是否应监视应用中内容声明文件的更改,以重建相关字典。
775
-
776
- - **fileExtensions**:
777
- - _类型_:`string[]`
778
- - _默认值_: `['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']`
779
- - _描述_: 构建字典时要查找的文件扩展名。
780
- - _示例_: `['.data.ts', '.data.js', '.data.json']`
781
- - _备注_: 自定义文件扩展名可以帮助避免冲突。
782
-
783
- - **dictionaryOutput**:
784
- - _类型_: `string[]`
785
- - _默认值_: `['intlayer']`
786
- - _描述_: 使用的字典输出类型,例如 `'intlayer'` 或 `'i18next'`。
787
-
788
- - **contentDir**:
789
- - _类型_: `string[]`
790
- - _默认值_: `['.']`
791
- - _示例_: `['src', '../../ui-library', require.resolve("@my-package/content")]`
792
- - _描述_: 存储内容定义文件(`.content.*`)的目录路径。
793
- - _备注_: 用于监视内容文件以重建字典。
794
-
795
- - **codeDir**:
796
- - _类型_: `string[]`
797
- - _默认值_: `['.']`
798
- - _示例_: `['src', '../../ui-library']`
799
- - _描述_: 存储代码的目录路径,相对于基础目录。
800
- - _备注_: 用于监视代码文件以进行转换(修剪、优化)。将此与 `contentDir` 分开可以提高构建性能,避免不必要地扫描内容文件。
575
+ ### 编辑器配置 (Editor Configuration)
576
+
577
+ 定义与集成编辑器相关的设置,包括服务器端口和活动状态。
578
+
579
+ | 字段 | 类型 | 说明 | 示例 | 备注 |
580
+ | ---------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
581
+ | `applicationURL` | `string` | 应用程序的 URL。默认值: `''` | `'http://localhost:3000'`, `'https://example.com'`, `process.env.INTLAYER_EDITOR_URL` | 用于出于安全原因限制编辑器的源 (origin)。如果设置为 `'*'`,则可以从任何源访问编辑器。 |
582
+ | `port` | `number` | 可视化编辑器服务器使用的端口。默认值: `8000` | | |
583
+ | `editorURL` | `string` | 编辑器服务器的 URL。默认值: `'http://localhost:8000'` | `'http://localhost:3000'`, `'https://example.com'`, `process.env.INTLAYER_EDITOR_URL` | 用于限制可以与应用程序交互的源。如果设置为 `'*'`,则可从任何源访问。在更改端口或编辑器托管在其他域名时必须进行设置。 |
584
+ | `cmsURL` | `string` | Intlayer CMS URL。默认值: `'https://intlayer.org'` | `'https://intlayer.org'` | |
585
+ | `backendURL` | `string` | 后端服务器 URL。默认值: `https://back.intlayer.org` | `http://localhost:4000` | |
586
+ | `enabled` | `boolean` | 指示应用是否将与可视化编辑器交互。默认值: `true` | `process.env.NODE_ENV !== 'production'` | 如果为 `false`,则编辑器无法与应用交互。针对特定环境禁用它可以增强安全性。 |
587
+ | `clientId` | `string &#124; undefined` | 允许 intlayer 包使用 oAuth2 在后端进行身份验证。要获取访问令牌,请访问 [intlayer.org/project](https://app.intlayer.org/project)。默认值: `undefined` | | 请保密;存储在环境变量中。 |
588
+ | `clientSecret` | `string &#124; undefined` | 允许 intlayer 包使用 oAuth2 在后端进行身份验证。要获取访问令牌,请访问 [intlayer.org/project](https://app.intlayer.org/project)。默认值: `undefined` | | 请保密;存储在环境变量中。 |
589
+ | `dictionaryPriorityStrategy` | `string` | 当本地字典和远程字典同时存在时字典优先级策略。默认值: `'local_first'` | `'distant_first'` | `'distant_first'`: 远程优先于本地。 `'local_first'`: 本地优先于远程。 |
590
+ | `liveSync` | `boolean` | 指示当在 CMS / 可视化编辑器 / 后端检测到更改时,应用服务器是否应热重载内容。默认值: `true` | `true` | 当添加/更新字典时,应用会更新页面内容。实时同步将内容外包给另一个服务器,这可能会对性能产生轻微影响。建议将两者托管在同一台机器上。 |
591
+ | `liveSyncPort` | `number` | 实时同步服务器端口。默认值: `4000` | `4000` | |
592
+ | `liveSyncURL` | `string` | 实时同步服务器 URL。默认值: `'http://localhost:{liveSyncPort}'` | `'https://example.com'` | 默认指向 localhost;可以更改为远程实时同步服务器。 |
593
+
594
+ ### 路由配置 (Routing Configuration)
595
+
596
+ 控制路由行为的设置,包括 URL 结构、语言环境存储和中间件处理。
597
+
598
+ | 字段 | 类型 | 说明 | 示例 | 备注 |
599
+ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
600
+ | `mode` | `'prefix-no-default' &#124; 'prefix-all' &#124; 'no-prefix' &#124; 'search-params'` | 处理语言环境的 URL 路由模式。默认值: `'prefix-no-default'` | `'prefix-no-default'`: `/dashboard` (en) 或 `/fr/dashboard` (fr)。 `'prefix-all'`: `/en/dashboard`。 `'no-prefix'`: 语言环境通过其他方式处理。 `'search-params'`: `/dashboard?locale=fr` | 不影响 Cookie 或语言环境存储管理。 |
601
+ | `storage` | `false &#124; 'cookie' &#124; 'localStorage' &#124; 'sessionStorage' &#124; 'header' &#124; CookiesAttributes &#124; StorageAttributes &#124; Array` | 在客户端存储语言环境的配置。默认值: `['cookie', 'header']` | `'localStorage'`, `[{ type: 'cookie', name: 'custom-locale', secure: true }]` | 请参阅下方的“存储选项”表。 |
602
+ | `basePath` | `string` | 应用程序 URL 的基础路径。默认值: `''` | `'/my-app'` | 如果应用程序位于 `https://example.com/my-app`,则 basePath 为 `'/my-app'`,URL 变为 `https://example.com/my-app/en`。 |
603
+ | `rewrite` | `Record<string, StrictModeLocaleMap<string>>` | 自定义 URL 重写规则,针对特定路径覆盖默认路由模式。支持动态参数 `[param]`。默认值: `undefined` | 请参阅下方示例 | 重写规则优先于 `mode`。适用于 Next.js 和 Vite。`getLocalizedUrl()` 会自动应用匹配的规则。请参阅 [自定义 URL 重写](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/custom_url_rewrites.md)。 |
604
+
605
+ **`rewrite` 示例**:
606
+
607
+ ```typescript
608
+ routing: {
609
+ mode: "prefix-no-default", // 回退策略
610
+ rewrite: nextjsRewrite({
611
+ "/about": {
612
+ en: "/about",
613
+ fr: "/a-propos",
614
+ },
615
+ "/product/[slug]": {
616
+ en: "/product/[slug]",
617
+ fr: "/produit/[slug]",
618
+ },
619
+ "/blog/[category]/[id]": {
620
+ en: "/blog/[category]/[id]",
621
+ fr: "/journal/[category]/[id]",
622
+ },
623
+ }),
624
+ }
625
+ ```
626
+
627
+ #### 存储选项 (Storage Options)
628
+
629
+ | 值 | 说明 | 备注 |
630
+ | ------------------ | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
631
+ | `'cookie'` | 将语言环境存储在 Cookie 中 — 客户端和服务器端均可访问。 | 为了符合 GDPR,请确保已获得适当的用户同意。可通过 `CookiesAttributes` 自定义 (`{ type: 'cookie', name: 'custom-locale', secure: true, httpOnly: false }`)。 |
632
+ | `'localStorage'` | 将语言环境存储在浏览器中,没有过期日期 — 仅限客户端。 | 除非明确清除,否则不会过期。Intlayer 代理无法访问。可通过 `StorageAttributes` 自定义 (`{ type: 'localStorage', name: 'custom-locale' }`)。 |
633
+ | `'sessionStorage'` | 在页面会话期间存储语言环境 — 仅限客户端。 | 关闭标签页/窗口时将被清除。Intlayer 代理无法访问。可通过 `StorageAttributes` 自定义 (`{ type: 'sessionStorage', name: 'custom-locale' }`)。 |
634
+ | `'header'` | 通过 HTTP 头存储或传输语言环境 — 仅限服务器端。 | 对于 API 调用非常有用。客户端无法访问。可通过 `StorageAttributes` 自定义 (`{ type: 'header', name: 'custom-locale' }`)。 |
635
+
636
+ #### Cookie 属性 (Cookie Attributes)
637
+
638
+ 使用 Cookie 存储时,您可以配置额外的 Cookie 属性:
639
+
640
+ | 字段 | 类型 | 说明 |
641
+ | ---------- | ------------------------------------- | ---------------------------------------- |
642
+ | `name` | `string` | Cookie 名称。默认值: `'INTLAYER_LOCALE'` |
643
+ | `domain` | `string` | Cookie 域名。默认值: `undefined` |
644
+ | `path` | `string` | Cookie 路径。默认值: `undefined` |
645
+ | `secure` | `boolean` | 要求 HTTPS。默认值: `undefined` |
646
+ | `httpOnly` | `boolean` | HTTP-only 标志。默认值: `undefined` |
647
+ | `sameSite` | `'strict' &#124; 'lax' &#124; 'none'` | SameSite 策略。 |
648
+ | `expires` | `Date &#124; number` | 过期日期或天数。默认值: `undefined` |
649
+
650
+ #### 语言环境存储属性 (Locale Storage Attributes)
651
+
652
+ 使用 localStorage 或 sessionStorage 时:
653
+
654
+ | 字段 | 类型 | 说明 |
655
+ | ------ | ---------------------------------------- | ----------------------------------------- |
656
+ | `type` | `'localStorage' &#124; 'sessionStorage'` | 存储类型。 |
657
+ | `name` | `string` | 存储键的名称。默认值: `'INTLAYER_LOCALE'` |
658
+
659
+ #### 配置示例
660
+
661
+ 以下是新 v7 路由结构的一些常见配置示例:
662
+
663
+ **基础配置 (默认)**:
664
+
665
+ ```typescript
666
+ import { Locales, type IntlayerConfig } from "intlayer";
667
+ // intlayer.config.ts
668
+ const config: IntlayerConfig = {
669
+ internationalization: {
670
+ locales: ["en", "fr", "es"],
671
+ defaultLocale: "en",
672
+ },
673
+ routing: {
674
+ mode: "prefix-no-default",
675
+ storage: "localStorage",
676
+ basePath: "",
677
+ },
678
+ };
801
679
 
802
- ---
680
+ export default config;
681
+ ```
682
+
683
+ **符合 GDPR 的配置**:
684
+
685
+ ```typescript
686
+ import { Locales, type IntlayerConfig } from "intlayer";
687
+ // intlayer.config.ts
688
+ const config: IntlayerConfig = {
689
+ internationalization: {
690
+ locales: ["en", "fr", "es"],
691
+ defaultLocale: "en",
692
+ },
693
+ routing: {
694
+ mode: "prefix-no-default",
695
+ storage: [
696
+ {
697
+ type: "localStorage",
698
+ name: "user-locale",
699
+ },
700
+ {
701
+ type: "cookie",
702
+ name: "user-locale",
703
+ secure: true,
704
+ sameSite: "strict",
705
+ httpOnly: false,
706
+ },
707
+ ],
708
+ basePath: "",
709
+ },
710
+ };
711
+
712
+ export default config;
713
+ ```
714
+
715
+ **搜索参数模式 (Search Parameters Mode)**:
716
+
717
+ ```typescript
718
+ import { Locales, type IntlayerConfig } from "intlayer";
719
+ // intlayer.config.ts
720
+ const config: IntlayerConfig = {
721
+ internationalization: {
722
+ locales: ["en", "fr", "es"],
723
+ defaultLocale: "en",
724
+ },
725
+ routing: {
726
+ mode: "search-params",
727
+ storage: "localStorage",
728
+ basePath: "",
729
+ },
730
+ };
731
+
732
+ export default config;
733
+ ```
734
+
735
+ **带自定义存储的无前缀模式 (No Prefix Mode)**:
736
+
737
+ ```typescript
738
+ import { Locales, type IntlayerConfig } from "intlayer";
739
+ // intlayer.config.ts
740
+ const config: IntlayerConfig = {
741
+ internationalization: {
742
+ locales: ["en", "fr", "es"],
743
+ defaultLocale: "en",
744
+ },
745
+ routing: {
746
+ mode: "no-prefix",
747
+ storage: {
748
+ type: "sessionStorage",
749
+ name: "app-locale",
750
+ },
751
+ basePath: "/my-app",
752
+ },
753
+ };
803
754
 
804
- ### 系统配置
755
+ export default config;
756
+ ```
805
757
 
806
- Intlayer 内部路径和输出结果相关的设置。这些设置通常是内部的,用户无需修改。
758
+ **带有动态路径的自定义 URL 重写**:
807
759
 
808
- #### 属性
760
+ ```typescript
761
+ // intlayer.config.ts
762
+ import { nextjsRewrite } from "intlayer/routing";
809
763
 
810
- - **baseDir**:
811
- - _类型_: `string`
812
- - _默认值_: `process.cwd()`
813
- - _描述_: 项目的基础目录。
814
- - _示例_: `'/path/to/project'`
815
- - _备注_: 用于解析所有与 Intlayer 相关的目录。
764
+ const config: IntlayerConfig = {
765
+ internationalization: {
766
+ locales: ["en", "fr"],
767
+ defaultLocale: "en",
768
+ },
769
+ routing: {
770
+ mode: "prefix-no-default", // 针对未重写路径的回退策略
771
+ storage: "cookie",
772
+ rewrite: nextjsRewrite({
773
+ "/about": {
774
+ en: "/about",
775
+ fr: "/a-propos",
776
+ },
777
+ "/product/[slug]": {
778
+ en: "/product/[slug]",
779
+ fr: "/produit/[slug]",
780
+ },
781
+ "/blog/[category]/[id]": {
782
+ en: "/blog/[category]/[id]",
783
+ fr: "/journal/[category]/[id]",
784
+ },
785
+ }),
786
+ },
787
+ };
816
788
 
817
- - **dictionariesDir**:
818
- - _类型_: `string`
819
- - _默认值_: `'.intlayer/dictionary'`
820
- - _描述_: 用于存储本地化词典的目录。
821
- - _示例_: `'translations'`
789
+ export default config;
790
+ ```
822
791
 
823
- - **moduleAugmentationDir**:
824
- - _类型_: `string`
825
- - _默认_: `'.intlayer/types'`
826
- - _描述_: 模块增强目录,允许更好的 IDE 提示和类型检查。
827
- - _示例_: `'intlayer-types'`
828
- - _注意_: 确保在 `tsconfig.json` 中包含此目录。
792
+ ---
829
793
 
830
- - **unmergedDictionariesDir**:
831
- - _类型_: `string`
832
- - _默认_: `'.intlayer/unmerged_dictionary'`
833
- - _描述_: 用于存储未合并字典的目录。
834
- - _示例_: `'translations'`
794
+ ### 内容配置 (Content Configuration)
835
795
 
836
- - **typesDir**:
837
- - _类型_: `string`
838
- - _默认值_: `'types'`
839
- - _描述_: 用于存储词典类型的目录。
840
- - _示例_: `'intlayer-types'`
796
+ 与应用程序中的内容处理相关的设置 (目录名、文件扩展名和衍生配置)。
841
797
 
842
- - **mainDir**:
843
- - _类型_: `string`
844
- - _默认值_: `'main'`
845
- - _描述_: 存放主应用程序文件的目录。
846
- - _示例_: `'intlayer-main'`
798
+ | 字段 | 类型 | 说明 | 示例 | 备注 |
799
+ | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------- |
800
+ | `watch` | `boolean` | 指示 Intlayer 是否应监视内容声明文件的更改以重新构建字典。默认值: `process.env.NODE_ENV === 'development'` | | |
801
+ | `fileExtensions` | `string[]` | 用于扫描内容声明文件的文件扩展名。默认值: `['.content.ts', '.content.js', '.content.mjs', '.content.cjs', '.content.json', '.content.json5', '.content.jsonc']` | `['.content.ts', '.content.js']` | |
802
+ | `contentDir` | `string[]` | 内容声明文件所在目录的路径。默认值: `['.']` | `['src/content']` | |
803
+ | `codeDir` | `string[]` | 应用程序源代码文件所在目录的路径。默认值: `['.']` | `['src']` | 用于优化构建,并确保代码转换和热重载仅应用于必要的文件。 |
804
+ | `excludedPath` | `string[]` | 内容扫描中排除的路径。默认值: `['node_modules', '.intlayer', '.next', 'dist', 'build']` | `['src/styles']` | |
805
+ | `formatCommand` | `string` | 将为格式化新创建或更新的内容文件而运行的命令。默认值: `undefined` | `'npx prettier --write "{{file}}"'` | 在内容提取期间或通过可视化编辑器使用。 |
847
806
 
848
- - **excludedPath**:
849
- - _类型_: `string[]`
850
- - _默认值_: `['node_modules']`
851
- - _描述_: 排除内容搜索的目录。
852
- - _备注_: 此设置尚未使用,但计划在未来实现。
807
+ ---
853
808
 
854
- ### 字典配置
809
+ ### 字典配置 (Dictionary Configuration)
855
810
 
856
- 控制字典操作的设置,包括自动填充行为和内容生成。
811
+ 控制字典操作,包括自动填充行为和内容生成。
857
812
 
858
813
  此字典配置有两个主要目的:
859
814
 
860
815
  1. **默认值**:在创建内容声明文件时定义默认值
861
816
  2. **回退行为**:当未定义特定字段时提供回退值,允许您全局定义字典操作行为
862
817
 
863
- 有关内容声明文件以及如何应用配置值的更多信息,请参阅[内容文件文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
864
-
865
- #### 属性
866
-
867
- - **fill**
868
- - **description**
869
- - **locale**
870
- - **location**
871
- - **importMode**:
872
- - _注意_: **Deprecated**: Use `dictionary.importMode` instead.
873
- - _类型_: `'static' | 'dynamic' | 'fetch'`
874
- - _默认值_: `'static'`
875
- - _描述_: Controls how dictionaries are imported.
876
- - _示例_: `'dynamic'`
877
- - **priority**
878
- - **live**
879
- - **schema**
880
- - **title**
881
- - **tags**
882
- - **version**
818
+ 有关内容声明文件以及配置值如何应用的更多信息,请参阅 [内容文件文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
819
+
820
+ | 字段 | 类型 | 说明 | 示例 | 备注 |
821
+ | --------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
822
+ | `fill` | `boolean &#124; FilePathPattern &#124; Partial<Record<Locale, boolean &#124; FilePathPattern>>` | 控制自动填充(AI 翻译)输出文件的生成方式。默认值: `true` | 请参阅下方示例 | `true`: 默认路径(与源文件相同)。`false`: 禁用。字符串/函数模板为每个语言环境生成文件。每个语言环境的对象:每个语言环境映射到其自己的模式;`false` 跳过该语言环境。包含 `{{locale}}` 会触发每个语言环境的生成。字典级别的 `fill` 始终优先于此全局配置。 |
823
+ | `importMode` | `'static' &#124; 'dynamic' &#124; 'fetch'` | 控制字典的导入方式。默认值: `'static'` | `'dynamic'` | `'static'`: 静态导入。`'dynamic'`: 通过 Suspense 动态导入。`'fetch'`: 通过实时同步 API 动态获取。不影响 `getIntlayer`, `getDictionary`, `useDictionary` 等。 |
824
+ | `location` | `'local' &#124; 'remote' &#124; 'hybrid' &#124; string` | 字典存储的位置。默认值: `'local'` | `'remote'` | `'local'`: 文件系统。`'remote'`: Intlayer CMS。`'hybrid'`: 两者。 |
825
+ | `contentAutoTransformation` | `boolean` | 内容文件是否应自动转换 (例如:从 Markdown 到 HTML)。默认值: `false` | `true` | 有助于通过 @intlayer/markdown 处理 Markdown 字段。 |
826
+
827
+ **`fill` 示例**:
828
+
829
+ ```ts
830
+ dictionary: {
831
+ fill: {
832
+ en: '/locales/en/{{key}}.content.json',
833
+ fr: ({ key }) => `/locales/fr/${key}.content.json`,
834
+ es: false,
835
+ }
836
+ }
837
+ ```
838
+
839
+ ---
840
+
841
+ ### AI 配置 (AI Configuration)
842
+
843
+ 定义 Intlayer AI 驱动功能 (如翻译构建) 的设置。
844
+
845
+ | 字段 | 类型 | 说明 | 示例 | 备注 |
846
+ | -------------------- | ---------------------- | ---------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------ |
847
+ | `provider` | `string` | 要使用的 AI 提供商。 | `'openai'`, `'anthropic'`, `'googlevertex'` | |
848
+ | `model` | `string` | 要使用的 AI 模型。 | `'gpt-4o'`, `'claude-3-5-sonnet-20240620'` | |
849
+ | `apiKey` | `string` | 所选提供商的 API 密钥。 | `process.env.OPENAI_API_KEY` | |
850
+ | `applicationContext` | `string` | 有关您应用程序的额外上下文,以提高 AI 翻译的准确性。 | `'面向儿童的学习平台。'` | |
851
+ | `baseURL` | `string` | API 调用的可选基础 URL。 | | 如果您使用代理或本地 AI 部署,这很有用。 |
852
+ | `dataSerialization` | `'json' &#124; 'toon'` | 定义如何向 AI 发送数据。默认值: `'json'` | `'json'` | `'json'`: 更稳健精确。 `'toon'`: 消耗 Token 较少,但可能不太稳定。 |
883
853
 
884
854
  ---
885
855
 
886
- ### 日志配置
887
-
888
- 控制日志记录器的设置,包括使用的前缀。
889
-
890
- #### 属性
891
-
892
- - **mode**:
893
- - _类型_: `string`
894
- - _默认值_: `default`
895
- - _描述_: 指示日志记录器的模式。
896
- - _选项_: `default`,`verbose`,`disabled`
897
- - _示例_: `default`
898
- - _备注_: 日志记录器的模式。详细模式将记录更多信息,可用于调试。禁用模式将关闭日志记录器。
899
-
900
- - **prefix**:
901
- - _类型_: `string`
902
- - _默认值_: `'[intlayer] '`
903
- - _描述_: 日志记录器的前缀。
904
- - _示例_: `'[my custom prefix] '`
905
- - _注释_: 日志器的前缀。
906
-
907
- ### AI 配置
908
-
909
- 控制 Intlayer AI 功能的设置,包括提供商、模型和 API 密钥。
910
-
911
- 如果您已使用访问密钥在[Intlayer 控制面板](https://app.intlayer.org/project)注册,则此配置是可选的。Intlayer 会自动管理最有效且具有成本效益的 AI 解决方案以满足您的需求。使用默认选项可确保更好的长期可维护性,因为 Intlayer 会持续更新以使用最相关的模型。
912
-
913
- 如果您希望使用自己的 API 密钥或特定模型,可以定义自定义的 AI 配置。
914
- 此 AI 配置将在整个 Intlayer 环境中全局使用。CLI 命令将使用这些设置作为命令的默认值(例如 `fill`),同时 SDK、可视化编辑器和 CMS 也会使用这些默认值。您可以通过命令参数覆盖这些默认值以满足特定用例。
915
-
916
- Intlayer 支持多个 AI 提供商,以增强灵活性和选择。目前支持的提供商有:
917
-
918
- - **OpenAI**(默认)
919
- - **Anthropic Claude**
920
- - **Mistral AI**
921
- - **DeepSeek**
922
- - **Google Gemini**
923
- - **Meta Llama**
924
- - **Ollama**
925
- - **OpenRouter**
926
- - **Alibaba Cloud**
927
- - **Fireworks**
928
- - **Hugging Face**
929
- - **Groq**
930
- - **Amazon Bedrock**
931
- - **Google AI Studio**
932
- - **Google Vertex**
933
- - **Together.ai**
934
- - **ollama**
935
-
936
- #### 属性
937
-
938
- - **provider**:
939
- - _类型_:`string`
940
- - _默认值_:`'openai'`
941
- - _描述_:用于 Intlayer AI 功能的提供商。
942
- - _选项_:`'openai'`、`'anthropic'`、`'mistral'`、`'deepseek'`、`'gemini'`
943
- - _示例_:`'anthropic'`
944
- - _注意_: 不同的提供商可能需要不同的 API 密钥,并且有不同的定价模型。
945
-
946
- - **model**:
947
- - _类型_: `string`
948
- - _默认值_: 无
949
- - _描述_: 用于 Intlayer AI 功能的模型。
950
- - _示例_: `'gpt-4o-2024-11-20'`
951
- - _注意_: 具体使用的模型因提供商而异。
952
-
953
- - **temperature**:
954
- - _类型_: `number`
955
- - _默认值_: 无
956
- - _描述_: temperature 控制 AI 回答的随机性。
957
- - _示例_: `0.1`
958
- - _注意_: 较高的 temperature 会使 AI 更具创造性且不可预测。
959
-
960
- - **apiKey**:
961
- - _类型_: `string`
962
- - _默认值_: 无
963
- - _描述_: 你为所选提供商提供的 API 密钥。
964
- - _示例_: `process.env.OPENAI_API_KEY`
965
- - _注意_: 重要提示:API 密钥应保密,切勿公开共享。请确保将其保存在安全的位置,例如环境变量中。
966
-
967
- - **applicationContext**:
968
- - _类型_: `string`
969
- - _默认值_: 无
970
- - _描述_: 向 AI 模型提供有关您的应用程序的额外上下文,帮助其生成更准确且符合上下文的翻译。这可以包括您的应用领域、目标受众、语气或特定术语的信息。
971
-
972
- - **baseURL**:
973
- - _类型_: `string`
974
- - _默认值_: 无
975
- - _描述_: AI API 的基础 URL。
976
- - _示例_: `'https://api.openai.com/v1'`
977
- - _注意_: 可用于指向本地或自定义的 AI API 端点。
978
-
979
- - **dataSerialization**:
980
- - _类型_: `'json' | 'toon'`
981
- - _默认值_: `'json'`
982
- - _描述_: 用于 Intlayer AI 功能的数据序列化格式。
983
- - _示例_: `'toon'`
984
- - _注意_: `json`: 标准、可靠;使用更多令牌。`toon`: 令牌更少,但不如 JSON 一致。
985
-
986
- ### 构建配置
987
-
988
- 控制 Intlayer 如何优化和构建您的应用程序国际化的设置。
989
-
990
- 构建选项适用于 `@intlayer/babel` 和 `@intlayer/swc` 插件。
991
-
992
- > 在开发模式下,Intlayer 使用静态导入字典,以简化开发体验。
993
-
994
- > 在优化模式下,Intlayer 会替换字典调用以优化代码分块,因此最终打包只会导入实际使用的字典。
995
-
996
- #### 属性
997
-
998
- - **mode**:
999
- - _类型_:`'auto' | 'manual'`
1000
- - _默认值_:`'auto'`
1001
- - _描述_:控制构建的模式。
1002
- - _示例_:`'manual'`
1003
- - _注意_:如果为 'auto',构建将在应用程序构建时自动启用。
1004
- - _注意_:如果为 'manual',构建仅在执行构建命令时设置。
1005
- - _注意_:可用于禁用字典构建,例如当应避免在 Node.js 环境中执行时。
1006
-
1007
- - **checkTypes**:
1008
- - _类型_: `boolean`
1009
- - _默认值_: `false`
1010
- - _描述_: 指示构建是否应检查 TypeScript 类型并记录错误。
1011
- - _注意_: 这可能会减慢构建速度。
1012
-
1013
- - **optimize**:
1014
- - _类型_:`boolean`
1015
- - _默认值_:`process.env.NODE_ENV === 'production'`
1016
- - _描述_:控制构建是否应进行优化。
1017
- - _示例_:`true`
1018
- - _注意_:启用时,Intlayer 会替换所有字典调用以优化代码分块。这样最终打包只会导入被使用的字典。所有导入将保持为静态导入,以避免加载字典时的异步处理。
1019
- - _注意_: Intlayer 会根据 `importMode` 选项定义的模式替换所有 `useIntlayer` 的调用,并将 `getIntlayer` 替换为 `getDictionary`。
1020
- - _注意_: 此选项依赖于 `@intlayer/babel` 和 `@intlayer/swc` 插件。
1021
- - _注意_: 确保所有键在 `useIntlayer` 调用中是静态声明的。例如 `useIntlayer('navbar')`。
1022
-
1023
- - **outputFormat**:
1024
- - _类型_: `'esm' | 'cjs'`
1025
- - _默认值_: `'esm'`
1026
- - _描述_: 控制字典的输出格式。
1027
- - _示例_: `'cjs'`
1028
- - _注意_: 字典的输出格式。
1029
-
1030
- - **traversePattern**:
1031
- - _类型_: `string[]`
1032
- - _默认值_: `['**\/*.{js,ts,mjs,cjs,jsx,tsx}', '!**\/node_modules/**']`
1033
- - _描述_:定义在优化过程中应遍历哪些文件的模式。
1034
- - _示例_:`['src/**\/*.{ts,tsx}', '../ui-library/**\/*.{ts,tsx}', '!**/node_modules/**']`
1035
- - _注意_:使用此选项限制优化范围到相关代码文件,以提升构建性能。
1036
- - _注意_:如果禁用 `optimize`,此选项将被忽略。
1037
- - _注意_:使用 glob 模式。
856
+ ### 构建配置 (Build Configuration)
857
+
858
+ Intlayer 构建流程和优化设置。
859
+
860
+ | 字段 | 类型 | 说明 | 示例 | 备注 |
861
+ | -------------- | ------------------------ | --------------------------------------------------------------------- | ---- | ---- |
862
+ | `mode` | `'auto' &#124; 'manual'` | 指示 Intlayer 是否应在应用预构建步骤期间自动运行。默认值: `'auto'` | | |
863
+ | `optimize` | `boolean` | 指示编译后的字典是否应针对运行时进行优化。默认值: 生产环境下为 `true` | | |
864
+ | `outputFormat` | `('cjs' &#124; 'esm')[]` | 生成的字典文件的输出格式。默认值: `['cjs', 'esm']` | | |
865
+ | `checkTypes` | `boolean` | 指示 Intlayer 是否应检查生成文件中的类型。默认值: `false` | | |
1038
866
 
1039
867
  ---
1040
868
 
1041
- ### 编译器配置
1042
-
1043
- 控制 Intlayer 编译器的设置,该编译器直接从您的组件中提取字典。
1044
-
1045
- #### 属性
1046
-
1047
- - **enabled**:
1048
- - _类型_:`boolean | 'build-only'`
1049
- - _默认值_:`true`
1050
- - _描述_:指示是否应启用编译器以提取字典。
1051
- - _示例_:`'build-only'`
1052
- - _注意_:设置为 `'build-only'` 将在开发模式下跳过编译器,以加快启动速度。它仅在构建命令时运行。
1053
-
1054
- - **dictionaryKeyPrefix**:
1055
- - _类型_:`string`
1056
- - _默认值_:`''`
1057
- - _描述_:提取的字典键的前缀。
1058
- - _示例_:`'my-key-'`
1059
- - _注意_:提取字典时,键是根据文件名生成的。此前缀会添加到生成的键中,以防止冲突。
1060
-
1061
- - **saveComponents**:
1062
- - _类型_:`boolean`
1063
- - _默认值_:`false`
1064
- - _描述_:指示是否应在转换后保存组件。
1065
- - _注意_:如果为 true,编译器将用转换后的文件替换原始文件。这样,编译器只需运行一次来转换应用,然后即可移除。
1066
-
1067
- - **transformPattern**:
1068
- - _类型_:`string | string[]`
1069
- - _默认值_:`['**/*.{ts,tsx,jsx,js,cjs,mjs,svelte,vue}', '!**/node_modules/**']`
1070
- - _描述_:定义在优化过程中应遍历哪些文件的模式。
1071
- - _示例_:`['src/**/*.{ts,tsx}', '!**/node_modules/**']`
1072
- - _注意_:使用此选项限制优化范围到相关代码文件,以提升构建性能。
1073
-
1074
- - **excludePattern**:
1075
- - _类型_:`string | string[]`
1076
- - _默认值_:`['**/node_modules/**']`
1077
- - _描述_:定义在优化过程中应排除哪些文件的模式。
1078
- - _示例_:`['**/node_modules/**', '!**/node_modules/react/**']`
1079
-
1080
- - **output**:
1081
- - _类型_: `FilePathPattern`
1082
- - _默认值_: `undefined`
1083
- - _描述_: 定义输出文件路径。替换 `outputDir`。通过字符串模板或函数支持动态变量。支持的变量:`{{fileName}}`, `{{key}}`, `{{locale}}`, `{{extension}}`, `{{componentFileName}}`, `{{componentExtension}}`, `{{format}}`, `{{componentFormat}}`, `{{componentDirPath}}`。
1084
- - _注意_: `./` 开头的路径相对于组件目录解析。以 `/` 开头的路径相对于项目根目录 (`baseDir`) 解析。
1085
- - _注意_: 在路径中包含 `{{locale}}` 变量将启用按语言环境分离开的字典生成。
1086
- - _示例_:
1087
- - **在组件旁边创建多语言文件**:
1088
- - 字符串: `'./{{fileName}}{{extension}}'`
1089
- - 函数: `({ fileName, extension }) => \`./${fileName}${extension}\``
1090
-
1091
- - **输出按语言环境集中的 JSON**:
1092
- - 字符串: `'/locales/{{locale}}/{{key}}.content.json'`
1093
- - 函数: `({ key, locale }) => \`/locales/${locale}/${key}.content.json\``
1094
-
1095
- - **noMetadata**:
1096
- - _类型_: `boolean`
1097
- - _默认值_: `false`
1098
- - _描述_: 指示是否应在文件中保存元数据。如果为 true,编译器将不会保存字典的元数据(键、内容包装器)。
1099
- - _注意_: 如果与 `loadJSON` 插件一起使用,则非常有用。对于每种语言的 i18next 或 ICU MessageFormat JSON 输出非常有用。
1100
- - _示例_:
1101
- 如果为 `true`:
1102
- ```json
1103
- {
1104
- "key": "value"
1105
- }
1106
- ```
1107
- 如果为 `false`:
1108
- ```json
1109
- {
1110
- "key": "value",
1111
- "content": {
1112
- "key": "value"
1113
- }
1114
- }
1115
- ```
869
+ ### 系统配置 (System Configuration)
870
+
871
+ 这些设置面向高级用例和 Intlayer 内部配置。
872
+
873
+ | 字段 | 类型 | 说明 | 默认值 |
874
+ | ------------------------- | -------- | ------------------------- | --------------------------------- |
875
+ | `dictionariesDir` | `string` | 编译后字典的目录。 | `'.intlayer/dictionary'` |
876
+ | `moduleAugmentationDir` | `string` | TypeScript 模块扩充目录。 | `'.intlayer/types'` |
877
+ | `unmergedDictionariesDir` | `string` | 未合并字典的目录。 | `'.intlayer/unmerged_dictionary'` |
878
+ | `typesDir` | `string` | 生成类型的目录。 | `'.intlayer/types'` |
879
+ | `mainDir` | `string` | 主要 Intlayer 文件目录。 | `'.intlayer/main'` |
880
+ | `configDir` | `string` | 编译后的配置文件目录。 | `'.intlayer/config'` |
881
+ | `cacheDir` | `string` | 缓存文件目录。 | `'.intlayer/cache'` |
882
+
883
+ ---
884
+
885
+ ### 编译器配置 (Compiler Configuration)
886
+
887
+ Intlayer 编译器 (`intlayer compiler`) 的设置。
888
+
889
+ | 字段 | 类型 | 说明 | 默认值 |
890
+ | --------------------- | ------------------------ | ----------------------------------------------------- | ------- |
891
+ | `enabled` | `boolean` | 指示编译器是否处于活动状态。 | `false` |
892
+ | `output` | `string &#124; Function` | 提取的字典的输出路径。 | |
893
+ | `saveComponents` | `boolean` | 指示是否应使用转换后的版本覆盖原始源文件。 | `false` |
894
+ | `noMetadata` | `boolean` | 如果为 `true`,编译器将不会在生成的文件中包含元数据。 | `false` |
895
+ | `dictionaryKeyPrefix` | `string` | 可选的字典键前缀。 | `''` |
896
+
897
+ ---
898
+
899
+ ### 日志记录器配置 (Logger Configuration)
900
+
901
+ 自定义 Intlayer 日志输出的设置。
902
+
903
+ | 字段 | 类型 | 说明 | 默认值 |
904
+ | -------- | ---------------------------------------------- | -------------- | -------------- |
905
+ | `mode` | `'default' &#124; 'verbose' &#124; 'disabled'` | 日志模式。 | `'default'` |
906
+ | `prefix` | `string` | 日志消息前缀。 | `'[intlayer]'` |
907
+
908
+ ---
909
+
910
+ ### 自定义架构 (Custom Schemas)
911
+
912
+ | 字段 | 类型 | 说明 |
913
+ | --------- | --------------------------- | ------------------------------------- |
914
+ | `schemas` | `Record<string, ZodSchema>` | 允许您定义 Zod 架构来验证字典的结构。 |
915
+
916
+ ---
917
+
918
+ ### 插件 (Plugins)
919
+
920
+ | 字段 | 类型 | 说明 |
921
+ | --------- | ------------------ | ---------------------------- |
922
+ | `plugins` | `IntlayerPlugin[]` | 要激活的 Intlayer 插件列表。 |