doc-i18n

Overview

FastGPT documentation uses a two-file i18n approach, with Chinese as the source language and English as the target language. Your task is to translate Chinese documentation into natural, fluent North American English, not a word-for-word literal translation.

Before starting translation, you must read and follow these shared rules in full:

• FastGPT Product Translation Guidelines
• FastGPT Proper Noun Glossary

The shared glossary is the single source of truth for product terminology and takes precedence over existing English documentation, terminology used by similar products, and general technical conventions. Do not maintain a second set of product terminology in this Skill.

File Structure

Documentation is located under the document/content/ directory and may be distributed across subdirectories such as docs/、self-host/ :

• Content files:{name}.mdx(Chinese) → {name}.en.mdx(English)
• Navigation files:meta.json(Chinese) → meta.en.json(English)

Workflow

1. Determine the translation scope

Two ways to determine which files need translation:

Automatic detection(when the user does not specify particular files):

• Run git diff --name-only and git diff --cached --name-only to detect changed Chinese files under document/ Chinese files changed
• Filter for .mdx(excluding .en.mdx) and meta.json(excluding meta.en.json）
• Check whether the corresponding English files exist or need updating

Manual specification: the user directly provides file paths or directories.

Regardless of which method is used, as long as the translation scope includes .mdx content files, the meta.json / meta.en.json in the same directory must be included in the scope of the check, to avoid missing navigation after new English content is added.

2. Translate content files (.mdx → .en.mdx)

For each Chinese .mdx file, generate or update the corresponding .en.mdx file.

Before translating, first match the shared glossary by the longest Chinese phrase. For example,知识库引用 must be matched as a whole as Dataset citation(s), and must not be split into 知识库 and 引用 to be handled separately. Adjust capitalization and singular/plural forms according to the document grammar, but do not switch to the prohibited translations listed in the glossary.

Parts that remain unchanged：

• MDX import statements (such as import { Alert } from '@/components/docs/Alert'）
• Image paths (such as ![](/imgs/intro/image1.png)）
• Link URLs (keep the original URL unchanged)
• HTML/JSX component structure and properties (such as <Alert icon="🤖" context="success">）
• The markdown structure of tables
• Code block content (unless it is a Chinese comment)
• Emoji symbols

Parts that need translation：

• The frontmatter title and description
• All body text content
• Text content within components (such as text within an Alert)
• Text content in tables
• Chinese comments in code blocks

3. Sync navigation files (meta.json → meta.en.json)

For each Chinese meta.json, generate or update the corresponding meta.en.json. When translating .mdx files, also check the navigation file in the same directory:

• If the same directory contains meta.json, check whether the basename of the Chinese file translated this time (e.g., 41503.mdx → 41503) is in the pages array.
• If the Chinese file is a newly added page and meta.json is not referenced, update meta.jsonaccording to the existing ordering and context in the directory; if the position cannot be reliably determined, ask the user first, and do not just create .en.mdx and then ignore the navigation.
• meta.en.json of pages must be consistent with meta.json only translate title、description and separator strings; do not translate or delete page filename references.
• If meta.en.json is missing, it must be created; if it already exists but pages lags behind meta.json, it must be synchronized.
• If the user has only specified meta.json, still update meta.en.jsonaccording to the navigation file translation rules, and check whether the Chinese pages referenced in .mdx has a corresponding .en.mdx。
• When modifying navigation JSON, prefer using a structured JSON approach or strictly preserve the original file format, to avoid manual edits causing trailing commas, indentation drift, or pages ordering errors.

Fields to translate：title、description, separator strings (e.g., "---入门---" → "---Getting Started---"）

Fields to keep unchanged：pages filename references in the array,icon、root、order

4. After translation is complete

• Review all product terminology against the Chinese source text and the shared glossary; if prohibited translations are found, they must be corrected
• Search the English files for residual Chinese characters, and confirm item by item whether each is a brand name, a code example, or an omission in translation
• Manually review contextual terms in the glossary, for example 训练 should use Indexing、Processing or Reindex
• If you encounter terminology that is not included in the glossary and would affect consistency of product concepts, first report it to the user and confirm the recommended translation; do not fix new terminology on your own
• List all translated files
• List all updated meta.json / meta.en.json
• If you find that a Chinese file has a corresponding English file missing, remind the user
• If you find that a Chinese .mdx is not referenced by the meta.json in the same directory, and the navigation could not be safely updated this time, clearly remind the user

Translation principles

The core goal of these principles is to make North American developers feel that it reads like native English documentation, rather than a translation.

Language style

• Aimed at North American developers, use a natural American English technical writing style
• Do not translate word for word; convey the meaning and intent of the original text
• Technical documentation tends to be concise and direct, avoiding redundant embellishment
• Parallelism and elaboration commonly used in Chinese documentation should be condensed into expressions familiar to English readers when translated

Examples：

中文：可轻松导入各式各样的文档及数据，能自动对其开展知识结构化处理工作。
  ✗：You can easily import various documents and data, which will be automatically processed for knowledge structuring.
  ✓：Import documents and data with automatic knowledge structuring.

Localization of China-specific platforms and services

Use the international names directly; do not retain the original Chinese names:

Chinese	English
Feishu	Lark
WeCom	WeCom
DingTalk	DingTalk
Official Account	WeChat Official Account
ERNIE Bot	ERNIE Bot
Mainland China version	China Mainland
International version	International

Technical terminology

FastGPT product concepts must use the shared terminology glossary and must not be replaced because existing documentation or competing products use other names. For example:

• 知识库 → Dataset, not Knowledge Base
• 数据集 → Collection, not Dataset
• 节点、模块 → Node, not Module
• 调试 → Debug；试运行 → Test Run
• 引用 → Citation；知识库引用 → Dataset citation(s)
• 问题优化 → Query rewriting
• 索引模型 → Embedding model

For purely technical concepts not covered by the glossary, use industry-standard terms, for example LLM、Vector Store、Low-code. If referring to n8n or Dify, only compare the underlying product meaning; the FastGPT shared glossary always takes precedence.

Tone

• Maintain a professional but friendly tone, consistent with the style of the original document
• Do not be overly formal, and do not be too casual
• Aimed at developers and technical users, assume the reader has a basic technical background