概览
generaltranslation 库简介
介绍
generaltranslation 库是 GT 的核心 i18n 库，提供用于翻译和格式化的实用函数与类。
它通常与 gt-next 和 gt-react 等框架包搭配使用，也可作为独立库单独使用。
import { GT } from 'generaltranslation';
const gt = new GT({
apiKey: 'your-api-key',
projectId: 'your-project-id',
sourceLocale: 'en',
targetLocale: 'es',
});
// 翻译内容
const result = await gt.translate('Hello, world!', 'es');
// "¡Hola, mundo!"
// 格式化数字、日期和货币
const formattedPrice = gt.formatCurrency(29.99, 'USD');
const formattedDate = gt.formatDateTime(new Date());
// "$29.99"
// "9/25/2025"
// 处理语言区域设置
const localeProps = gt.getLocaleProperties('fr-CA');
const isValid = gt.isValidLocale('de');
// { language: "fr", region: "CA", ... }
// true安装
npm install generaltranslationyarn add generaltranslationbun add generaltranslationpnpm add generaltranslation示例
翻译主要分为两类：字符串翻译和文件翻译。
设置
要启用翻译，您需要提供项目 ID 和 API key。
请参阅 constructor 方法以了解更多信息。
const gt = new GT({
apiKey: 'your-api-key',
projectId: 'your-project-id',
targetLocale: 'es',
});字符串翻译
参阅 translate 方法以了解更多信息。
try {
const result = await gt.translate('Hello, world!');
console.log(result); // "¡Hola, mundo!"
} catch (error) {
console.error('翻译失败：', error.message);
}文件翻译
文件以“任务”的形式进行翻译。 上传文件即可启动一个任务。 一次上传多个文件会启动多个任务。
查看 uploadSourceFiles
和 checkFileTranslations 方法以了解更多信息。
// 要上传的文件
const files = [
{
source: {
fileName: 'src/components/Button.tsx',
fileFormat: 'TSX',
locale: 'en',
content: '...',
},
},
];
// 上传源文件
await gt.uploadSourceFiles(files);目录
GT 类
提供翻译与 locale 功能的主类：
- Constructor - 通过配置初始化 GT 实例
- setConfig - 更新 GT 实例的配置
翻译方法
- translate - 核心翻译功能
- translateMany - 批量翻译
- setupProject - 初始化项目
- shouldSetupProject - 检查是否需要进行项目初始化
- checkSetupStatus - 检查项目初始化状态
- getProjectData - 获取项目信息
- uploadSourceFiles - 上传源文件以供翻译
- enqueueFiles - 将文件加入处理队列
- checkFileTranslations - 检查翻译进度
- downloadTranslatedFile - 下载单个已翻译文件
- downloadFileBatch - 批量下载已翻译文件
- querySourceFile - 查询源文件信息
格式化方法
- formatMessage - 国际化文本的格式化
- formatNum - 数值格式化
- formatDateTime - 日期和时间格式化
Locale 方法
- getLocaleName - 获取 locale 的展示名称
- getLocaleProperties - 获取完整的 locale 资料
- getLocaleDirection - 获取 locale 的文本方向
- getLocaleEmoji - 获取 locale 的旗帜 emoji
- getRegionProperties - 获取地区信息和属性
- isValidLocale - 校验语言代码
- resolveAliasLocale - 将规范 locale 转换为别名
- resolveCanonicalLocale - 将别名 locale 转换为规范形式
- standardizeLocale - 规范化语言代码格式
- isSameDialect - 检查多个 locale 是否为相同方言
- isSameLanguage - 检查多个 locale 是否为相同语言
- isSupersetLocale - 检查 locale 的层级关系
- determineLocale - 从偏好中选出最匹配的 locale
- requiresTranslation - 判断是否需要翻译
实用工具函数
格式化函数
- formatMessage - 独立的文本格式化功能
- formatNum - 独立的数字格式化功能
- formatDateTime - 独立的日期/时间格式化功能
Locale 函数
- getLocaleName - 独立的 locale 名称工具
- getLocaleProperties - 独立的 locale 属性工具
- getLocaleDirection - 独立的文本方向工具
- getLocaleEmoji - 独立的 emoji 工具
- getRegionProperties - 独立的地区属性工具
- isValidLocale - 独立的 locale 校验工具
- resolveAliasLocale - 独立的 locale 别名解析工具
- standardizeLocale - 独立的 locale 标准化工具
- isSameDialect - 独立的方言比较工具
- isSameLanguage - 独立的语言比较工具
- isSupersetLocale - 独立的 locale 继承/包含关系检查工具
- determineLocale - 独立的 locale 协商工具
- requiresTranslation - 独立的翻译需求判断工具
类型与接口
TypeScript 定义：
- GTConstructorParams - 配置选项
- LocaleProperties - 完整的 locale 信息
- TranslationResult - 翻译结果类型
- TranslateManyResult - 批量翻译结果
- FileToTranslate - 文件翻译配置
- EnqueueFilesOptions - 文件入队选项
- Entry - 翻译 Entry 结构
- EntryMetadata - Entry 元数据
- Content - 内容类型定义
- Variable - Variable 结构
- VariableType - Variable 类型定义
- JsxElement - JSX 元素类型
- JsxChild - JSX 子节点类型
- JsxChildren - JsxChildren 类型
- DataFormat - DataFormat 规范
- CustomMapping - CustomMapping 配置
后续步骤
这份指南怎么样？