@guestlinelabs/onekey

中文文档
5.0.5发布于 2026/06/30ISCTypeScriptCommonJS近 30 天下载 1万

有 AI 翻译支持和 TypeScript 密钥生成的本地翻译管理工具

中文使用文档
文档目录43 节
  1. 安装
  2. 目录
  3. CLI 使用量
  4. 初始化翻译状态
  5. 同步翻译状态
  6. 检查翻译状态
  7. 与大赦国际一起翻译
  8. 地方跟踪
  9. 状态文件结构
  10. 关键特性
  11. 工作流程
  12. 程序化 API
  13. 国家管理职能
  14. 核心职能
  15. 文件操作
  16. 高级特性
  17. 地方政府
  18. 翻译春正
  19. 等级JSON支持
  20. 语言代码规范化
  21. 重试逻辑和错误处理
  22. 配置选项
  23. 高级整合
  24. 环境变量
  25. 项目结构
  26. 状态文件格式
  27. 类型脚本集成
  28. 生成类型
  29. 参数提取
  30. 应用程序中的使用
  31. 实例和最佳做法
  32. CI/CD 管道集成
  33. 构建脚本集成
  34. 完成本地工作流程
  35. 处理错误
  36. 从v4移徙
  37. 中断更改
  38. 移徙步骤
  39. 为什么五号更好
  40. 生成输出
  41. 输入结构
  42. 生成输出
  43. 关键特性

一键

一个带有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倍戳
  • 断层检测: 当基础语言比翻译更新时自动识别
  • 缺少翻译检测: 报告在基本地块中存在但没有在目标地块中存在的密钥

工作流程

  1. 初始化数字 : onekey init 扫描基本区域并创建初始状态
  2. 翻译数字 : onekey translate 仅更新陈旧的翻译和更新时间戳
  3. 检查数字 : onekey status 目前翻译健康
  4. 再次同步: 运行 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,以及 check CLI命令(及其相应的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)可提供.

移徙步骤

  1. 初始化本地状态

    onekey init -p ./translations -l en-GB
    
  2. 更新脚本

    v4 命令v5 替换
    onekey generateonekey sync
    onekey checkonekey status
    onekey fetch- (删除)
    onekey upload- (删除)
  3. 清洁环境变量

    unset ONESKY_PRIVATE_KEY
    unset ONESKY_PUBLIC_KEY
    # keep your OpenAI variables
    export OPENAI_API_KEY=your-key
    
  4. 方案用途

    - 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 });
    
  5. 校验 - 运行 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结构
  • 类型安全: 完整类型脚本集成与编译时间验证

版本与发布记录

@guestlinelabs/onekey 共发布 50 个版本,首次发布于 2020/12/23;过去 12 个月发布了 2 个版本。

版本发布日期距今
5.0.5latest2026/06/304 个月前
5.0.42026/01/209 个月前
5.0.32025/09/051.2 年前
5.0.22025/09/051.2 年前
5.0.12025/08/261.2 年前
5.0.02025/08/181.2 年前

其他发布通道:beta → 5.0.0-beta.4。

关于 @guestlinelabs/onekey 的常见问题

@guestlinelabs/onekey 是什么?

有 AI 翻译支持和 TypeScript 密钥生成的本地翻译管理工具

如何安装 @guestlinelabs/onekey?

在项目目录运行 npm install @guestlinelabs/onekey,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:prettier(2 || 3)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 onekey,可以用 npx onekey 直接运行。

@guestlinelabs/onekey 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guestlinelabs/onekey 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@guestlinelabs/onekey 可以商用吗?

@guestlinelabs/onekey 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@guestlinelabs/onekey 的下载量有多少?

根据 npm 官方下载统计,@guestlinelabs/onekey 在 2026/10/17 – 2026/11/15 这 30 天内被下载 10,002 次,日均约 333 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guestlinelabs/onekey 还在维护吗?

最新版本 5.0.5 发布于 2026/06/30(4 个月前);至今共发布 50 个版本,其中过去 12 个月发布了 2 个;首次发布于 2020/12/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。