一键
一个带有AI翻译支持和TypeScript密钥生成的本地翻译管理工具. OneKey为管理翻译提供了完整的全本地唯一的工作流程,并配有状态跟踪,AI动力翻译,以及类型安全的国际化.
安装
npm install @guestlinelabs/onekey
目录
CLI 使用量
OneKey提供仅本地的有状态跟踪的翻译工作流程:
初始化翻译状态
为翻译新鲜度管理设置了本地状态跟踪. 这是您在设置新翻译项目时应该运行的第一个命令 .
Usage: onekey init [options]
Options:
-p, --path Path to translations directory (default: ./translations)
-l, --baseLocale Base locale for translations (default: en)
--no-generate-keys Disable automatic generation of translation.ts
-y, --yes Skip interactive prompts and use defaults
-q, --quiet Suppress all output except errors
它会做什么:
- 扫描您的基本语言翻译文件
- 创建
oneKeyState.json对所有翻译密钥进行时间戳跟踪 - 建立翻译新鲜度跟踪的基础
- 配置自动生成
translation.ts(可用--no-generate-keys(中文(简体) )
示例
onekey init -p ./translations -l en
onekey init -p ./translations --no-generate-keys
同步翻译状态
同步翻译状态,生成 TypeScript 密钥,并报告 stale 翻译.
Usage: onekey sync [options]
它会做什么:
- 初始化新的未跟踪密钥和语言
- 生成
translation.ts(除非残疾) - 保存翻译的报表密钥( 比翻译的本地化更新)
- 缺少翻译的报告
- 如果找到问题, 则使用代码 1 退出
示例
onekey sync
检查翻译状态
只读检查已失效或缺失的翻译(CI/CD完美).
Usage: onekey status [options]
它会做什么:
- 装入
oneKeyState.json并比较各地的时间戳 - 保存翻译的报表密钥( 比翻译的本地化更新)
- 缺少翻译的报告
- 从不修改状态或生成文件
- 如果发现问题,则使用代码1退出(CI/CD完美)
示例
onekey status
与大赦国际一起翻译
使用AI将您的内容自动翻译为不同语言,具有智能状态跟踪功能. 默认情况下只翻译 stale 或 缺少的翻译 .
Usage: onekey translate [options]
Options:
-u, --api-url OpenAI API URL (fallback: OPENAI_API_URL env var)
-k, --api-key OpenAI API key (fallback: OPENAI_API_KEY env var)
-m, --api-model OpenAI API model (fallback: OPENAI_API_MODEL env var)
-c, --prettier-config Path to Prettier config file
-C, --context-file File with additional context for translations
-t, --tone Tone of the translation (formal / informal / neutral, default: neutral)
--update-all Re-translate all keys even if they are not stale
--stats Print stale key statistics per locale
状态助理翻译 :
- 只翻译已过时的密钥( 比目标 locale 更新的基数)
- 成功翻译后自动更新状态时间戳
- 使用
--updateAll以强制重翻译所有密钥 - 使用
--stats以查看每个区域存在多少个 stale 密钥
上下文文件支持 :
- 提供附加上下文的文本文件以提高翻译质量
- 例:"这些译名被用在酒店房间的预订引擎上"
翻译音调 :
formal- 讲礼貌和专业语言informal- 临时和友好语言neutral- 平衡调(默认)
环境变量:
OPENAI_API_URL- OpenAI API 端点( 返回 -- apiUrl)OPENAI_API_KEY- OpenAI API 密钥( 返回 -- apiKey )OPENAI_API_MODEL- OpenAI API模型( 返回 -- apiModel)
地方跟踪
OneKey 使用本地键 oneKeyState.json 文件可以跟踪翻译新鲜度,并管理翻译工作流程,而无需外部依赖.
状态文件结构
这个 oneKeyState.json 文件在您上次修改每个翻译密钥时的翻译目录和音轨中创建 :
{
"baseLocale": "en-GB",
"modified": {
"en-GB": {
"main.hello": { "lastModified": "2025-07-30T14:00:00Z" },
"main.goodbye": { "lastModified": "2025-07-30T14:05:00Z" },
"errors.validation.required": { "lastModified": "2025-07-30T14:03:00Z" }
},
"es-ES": {
"main.hello": { "lastModified": "2025-07-30T14:02:00Z" },
"main.goodbye": { "lastModified": "2025-07-30T14:01:00Z" }
}
}
}
关键特性
- 名称空格密钥:键用命名空间前缀(如,
main.hello, (中文(简体) ),errors.validation.required(中文(简体) ) - 时间戳跟踪: 用于精确修改跟踪的ISO-8601倍戳
- 断层检测: 当基础语言比翻译更新时自动识别
- 缺少翻译检测: 报告在基本地块中存在但没有在目标地块中存在的密钥
工作流程
- 初始化数字 :
onekey init扫描基本区域并创建初始状态 - 翻译数字 :
onekey translate仅更新陈旧的翻译和更新时间戳 - 检查数字 :
onekey status目前翻译健康 - 再次同步: 运行
onekey sync随时想再生translation.ts并刷新状态
程序化 API
库输出一些用于您节点Js应用程序的程序功能:
国家管理职能
负载状态( StatePath, base Locale)
从 JSON 文件装入翻译状态.
import { loadState } from "@guestlinelabs/onekey";
const state = await loadState("./translations/oneKeyState.json", "en-GB");
console.log(state.baseLocale); // 'en-GB'
console.log(state.modified); // Timestamp data
保存状态( StatePath, state)
将翻译状态保存到 JSON 文件.
import { saveState } from "@guestlinelabs/onekey";
await saveState("./translations/oneKeyState.json", state);
触摸( 状态、 语言、 密钥、 日期 )
更新特定翻译密钥的时间戳.
import { touch } from "@guestlinelabs/onekey";
touch(state, "en-GB", "main.hello", new Date());
isStale( 状态、 基础、 地方、 密钥)
检查译名是否为 stale( 比目标地块更新的地块) .
import { isStale } from "@guestlinelabs/onekey";
const stale = isStale(state, "en-GB", "es-ES", "main.hello");
console.log(stale); // true if es-ES translation is older than en-GB
diff状态( 状态)
生成所有已过时翻译的报告 .
import { diffState } from "@guestlinelabs/onekey";
const diffs = diffState(state);
// Returns array of { locale, key, baseTs, localeTs }
核心职能
生成关键字( 选项)
从翻译文件中生成 TypeScript 类型定义.
import { generateKeys } from "@guestlinelabs/onekey";
const typeDefinitions = await generateKeys({
languages: [
{
code: "en-GB",
englishName: "English",
localName: "English",
default: true,
},
],
translations: {
"main.json": {
hello: "Hello",
welcome: "Welcome, {{name}}",
},
},
defaultLocale: "en-GB",
prettierConfig: {},
});
console.log(typeDefinitions); // Generated TypeScript code
翻译( 选项)
使用带有状态跟踪的AI翻译内容.
import { translate } from "@guestlinelabs/onekey";
const result = await translate({
path: "./translations",
apiUrl: "https://api.openai.com/v1",
apiKey: "your-openai-key",
baseLocale: "en-GB",
context: "Hotel booking application",
tone: "formal",
updateAll: false, // Only translate stale keys
stats: true, // Print statistics
});
文件操作
保存关键字( 选项)
将生成的 TypeScript 密钥保存到文件 .
import { saveKeys } from "@guestlinelabs/onekey";
await saveKeys({
translationsPath: "./translations",
translationKeysPath: "./src/types",
defaultLocale: "en-GB",
prettierConfigPath: "./.prettierrc",
});
保存 Ai 翻译( 选项)
使用状态跟踪的AI翻译并保存内容.
import { saveAiTranslations } from "@guestlinelabs/onekey";
await saveAiTranslations({
path: "./translations",
apiUrl: "https://api.openai.com/v1",
apiKey: "your-openai-key",
baseLocale: "en-GB",
context: "E-commerce application",
tone: "friendly",
prettierConfigPath: "./.prettierrc",
updateAll: false, // Only translate stale keys
stats: true, // Print statistics
});
初始化状态( 选项)
初始化一个翻译项目的状态跟踪 .
import { initializeState } from "@guestlinelabs/onekey";
await initializeState({
translationsPath: "./translations",
baseLocale: "en-GB",
});
检查状态( 选项)
检查翻译状态并返回退出代码.
import { checkStatus } from "@guestlinelabs/onekey";
const exitCode = await checkStatus({
translationsPath: "./translations",
});
console.log(exitCode); // 0 if all good, 1 if issues found
高级特性
地方政府
OneKey提供精密的地方状态跟踪:
- 时间戳精度: 用于精确新鲜度跟踪的ISO-8601倍印章
- 名称空格密钥: 有命名空间前缀的平板键结构
- 断层检测: 各地修改时间的智能比较
- 缺少翻译检测: 识别基础中存在但没有目标位置的密钥
翻译春正
对于大型翻译文件,AI翻译功能自动:
- 分割大文件: 将翻译为100个密钥块
- 并行处理: 同时处理多块
- 内存优化:防止API超时和内存问题
- 状态更新: 仅在翻译成功后更新时间戳
等级JSON支持
支持嵌入式翻译结构 :
{
"user": {
"profile": {
"name": "Name",
"email": "Email"
}
}
}
生成平分键, 如 : "main.user.profile.name", (中文(简体) ), "main.user.profile.email"
语言代码规范化
库会自动将通用语言代码映射到其完整的地方标识符:
// Automatic mapping
'es' → 'es-ES'
'fr' → 'fr-FR'
'de' → 'de-DE'
'en' → 'en-GB'
// And more...
重试逻辑和错误处理
- 符号后退: 对失败的 API 请求, 自动重试, 并不断延迟
- 可配置的检索: 最多3次尝试, 5秒延迟
- 重大退化: 当单个文件失败时继续处理其他文件
- 国家一致性: 仅在操作成功后更新状态
配置选项
高级整合
所有文件操作支持 Pretier 格式化 :
// Automatic prettier config detection
await saveKeys({
// ... other options
prettierConfigPath: "./.prettierrc.json",
});
环境变量
库支持这些环境变量:
OPENAI_API_URL- OpenAI API 端点OPENAI_API_KEY- OpenAI API 密钥
项目结构
预期目录结构 :
translations/
├── oneKeyState.json # Translation state tracking
├── languages.json # Language definitions
├── en-GB/ # Base language
│ ├── main.json
│ └── errors.json
├── es-ES/ # Translated languages
│ ├── main.json
│ └── errors.json
└── translation.ts # Generated types
状态文件格式
这个 oneKeyState.json 文件结构 :
{
"baseLocale": "en-GB",
"modified": {
"en-GB": {
"main.hello": { "lastModified": "2025-07-30T14:00:00Z" },
"errors.validation.required": { "lastModified": "2025-07-30T14:05:00Z" }
},
"es-ES": {
"main.hello": { "lastModified": "2025-07-30T14:02:00Z" }
}
}
}
类型脚本集成
生成类型
库生成全面的类型脚本类型 :
// Generated types include:
export type Locale = "en-GB" | "es-ES" | "fr-FR";
export type Namespace = "main" | "errors";
export type TranslationKey = "main:hello" | "errors:unknown";
export type TranslationWithOptions = {
"main:welcome": { name: string };
};
export type Translator = {
(key: TranslationKeyWithoutOptions): string;
<T extends TranslationKeyWithOptions>(
key: T,
options: TranslationWithOptions[T]
): string;
};
参数提取
自动检测和类型翻译参数:
{
"welcome": "Hello, {{name}}!",
"items": "You have {{count}} items"
}
生成 :
type TranslationWithOptions = {
"main:welcome": { name: string };
"main:items": { count: number }; // 'count' is typed as number
};
应用程序中的使用
import type { TranslationKey, Translator } from "./translations/translation";
const t: Translator = (key, options) => {
// Your translation implementation
};
// Type-safe usage
t("main:hello"); // ✅ Valid
t("main:welcome", { name: "John" }); // ✅ Valid with required params
t("main:welcome"); // ❌ TypeScript error - missing required params
t("invalid:key"); // ❌ TypeScript error - invalid key
实例和最佳做法
CI/CD 管道集成
# .github/workflows/translations.yml
name: Check Translations
on: [push, pull_request]
jobs:
check-translations:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: "18"
- run: npm install
- run: npx onekey status -p ./translations
构建脚本集成
{
"scripts": {
"translations:init": "onekey init -p ./translations -l en-GB",
"translations:sync": "onekey sync",
"translations:status": "onekey status",
"translations:ai": "onekey translate --context ./translation-context.txt",
"translations:ai-all": "onekey translate --updateAll",
"translations:stats": "onekey translate --stats",
"build": "npm run translations:sync && next build"
}
}
完成本地工作流程
import {
initializeState,
checkStatus,
syncState,
translate,
loadState,
diffState,
} from "@guestlinelabs/onekey";
async function setupTranslations() {
// 1. Initialize state tracking
await initializeState({
translationsPath: "./translations",
baseLocale: "en-GB",
});
// 2. Sync state and generate translation.ts
const exitCode = await syncState();
if (exitCode === 0) {
console.log("All translations up to date!");
return;
}
// 3. Show stale translation statistics
const state = await loadState();
const diffs = diffState(state);
console.log(`Found ${diffs.length} stale translations`);
// 4. Translate stale keys only (syncState is called internally)
await translate({
path: "./translations",
apiUrl: process.env.OPENAI_API_URL!,
apiKey: process.env.OPENAI_API_KEY!,
context: "Hotel booking application",
tone: "formal",
stats: true,
});
console.log("Translations updated successfully!");
}
处理错误
import { translate, checkStatus } from "@guestlinelabs/onekey";
try {
await translate({
path: "./translations",
apiUrl: process.env.OPENAI_API_URL!,
apiKey: process.env.OPENAI_API_KEY!,
updateAll: false,
});
} catch (error) {
if (error.message.includes("Missing required parameters")) {
console.log("OpenAI API configuration required");
} else if (error.message.includes("Failed to initialize state")) {
console.log('Run "onekey init" first to set up state tracking');
} else {
console.error("Translation failed:", error);
}
}
// Check status with proper error handling
try {
const exitCode = await checkStatus({
translationsPath: "./translations",
});
if (exitCode === 1) {
console.log('Stale translations found - run "onekey translate" to update');
}
} catch (error) {
console.error("Status check failed:", error);
}
从v4移徙
一键 五进制 完全删除 OneSky 集成并引入仅本地状态跟踪. 使用此指南更新已有的 v4 项目 .
中断更改
- 已移除 OneSky - 那个
fetch, (中文(简体) ),upload,以及checkCLI命令(及其相应的API)已经消失. 所有译名现在全部存放在您的仓库中 . - 需要本地状态文件 -一个新的
oneKeyState.json文件( 创建于onekey init)存储每键时间戳,以便OneKey可以分辨翻译是停滞还是缺失. - 新建核心命令 – 说吧 –
init, (中文(简体) ),sync,以及status替换generate财务报告和审定财务报表check,添加自动状态管理。 这个translate命令现在是州意识,并添加像--update-all, (中文(简体) ),--stats, (中文(简体) ),--api-model等 (中文(简体) ). - 环境变量已改变 - 删除
ONESKY_PRIVATE_KEY财务报告和审定财务报表ONESKY_PUBLIC_KEY保留OPENAI_API_URL, (中文(简体) ),OPENAI_API_KEY,可选择OPENAI_API_MODEL。 。 。 . - API 表面更新 - OneSky函数(
fetchTranslations, (中文(简体) ),upload, (中文(简体) ),checkTranslations, (中文(简体) ),saveOneSkyTranslations页:1 新助手( E)initializeState, (中文(简体) ),syncState, (中文(简体) ),checkStatus, (中文(简体) ),loadState, (中文(简体) ),saveState, (中文(简体) ),touch, (中文(简体) ),isStale, (中文(简体) ),diffState)可提供.
移徙步骤
-
初始化本地状态
onekey init -p ./translations -l en-GB -
更新脚本
v4 命令 v5 替换 onekey generateonekey synconekey checkonekey statusonekey fetch- (删除) onekey upload- (删除) -
清洁环境变量
unset ONESKY_PRIVATE_KEY unset ONESKY_PUBLIC_KEY # keep your OpenAI variables export OPENAI_API_KEY=your-key -
方案用途
- import { fetchTranslations, upload, checkTranslations } from "@guestlinelabs/onekey"; + import { initializeState, syncState, checkStatus, translate } from "@guestlinelabs/onekey";典型的 v5 流量 :
await initializeState({ translationsPath: "./translations", baseLocale: "en-GB", }); await syncState(); await translate({ path: "./translations", stats: true }); -
校验 - 运行
onekey status退出代码0意味着一切是最新的;1表示过时或缺少翻译.
为什么五号更好
- 零外部依赖性 — 不呼叫 OneSky.
- 更快的增量 AI 翻译 – 只处理已更改的密钥 .
- 简单的 CI 检查
onekey status。 。 。 .
生成输出
这个 generate 命令从您的翻译文件中创建全面的 TypeScript 类型定义.
输入结构
// languages.json
[
{
"code": "en-GB",
"englishName": "English (United Kingdom)",
"localName": "English (United Kingdom)",
"default": true
},
{
"code": "es-ES",
"englishName": "Spanish (Spain)",
"localName": "Español (España)"
}
]
// en-GB/main.json
{
"hello": "Hello, friend",
"friendly_hello": "Hello, {{name}}",
"goodbye": "See you soon!",
"items_count": "You have {{count}} items"
}
// en-GB/errors.json
{
"hello": "Hello, seems there is a problem here!",
"unknown": "I don't know what happened, but looks bad!",
"validation": {
"required": "This field is required",
"email": "Please enter a valid email"
}
}
生成输出
// This file was autogenerated on 2024-01-15T10:30:00.000Z.
// DO NOT EDIT THIS FILE.
export const locales = ["en-GB", "es-ES"] as const;
export type Locale = (typeof locales)[number];
export const defaultLocale: Locale = "en-GB";
export const iso1ToLocale: { [key: string]: Locale } = {
en: "en-GB",
es: "es-ES",
};
export const languages: Array<{
code: Locale;
englishName: string;
localName: string;
}> = [
{
code: "en-GB",
englishName: "English (United Kingdom)",
localName: "English (United Kingdom)",
},
{
code: "es-ES",
englishName: "Spanish (Spain)",
localName: "Español (España)",
},
];
export type Namespace = "main" | "errors";
export const namespaces: Namespace[] = ["main", "errors"];
export type TranslationKeyWithoutOptions =
| "main:hello"
| "main:goodbye"
| "errors:hello"
| "errors:unknown"
| "errors:validation.required"
| "errors:validation.email";
export type TranslationWithOptions = {
"main:friendly_hello": { name: string };
"main:items_count": { count: number };
};
type TranslationKeyWithOptions = keyof TranslationWithOptions;
export type TranslationKey =
| TranslationKeyWithoutOptions
| TranslationKeyWithOptions;
export type Translator = {
(key: TranslationKeyWithoutOptions, options?: { count: number }): string;
<T extends TranslationKeyWithOptions>(
key: T,
options: TranslationWithOptions[T] & { count?: number }
): string;
};
关键特性
- 地方管理: 使用 ISO 映射来完成地方定义
- 命名空间支持: 由翻译文件名组织
- 参数打字: 自动检测
{{variable}}模式 - 特殊处理数字 :
count参数为number - 密钥: 支持带有点符号的分级JSON结构
- 类型安全: 完整类型脚本集成与编译时间验证