@guestlinelabs/onekey

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

Local translation management utility with AI translation support and TypeScript key generation

原始使用文档
文档目录43 节
  1. Installation
  2. Table of Contents
  3. CLI Usage
  4. Initialize translation state
  5. Sync translation state
  6. Check translation status
  7. Translate with AI
  8. Local State Tracking
  9. State File Structure
  10. Key Features
  11. Workflow
  12. Programmatic API
  13. State Management Functions
  14. Core Functions
  15. File Operations
  16. Advanced Features
  17. Local State Management
  18. Translation Chunking
  19. Hierarchical JSON Support
  20. Language Code Normalization
  21. Retry Logic and Error Handling
  22. Configuration Options
  23. Prettier Integration
  24. Environment Variables
  25. Project Structure
  26. State File Format
  27. TypeScript Integration
  28. Generated Types
  29. Parameter Extraction
  30. Usage in Applications
  31. Examples and Best Practices
  32. CI/CD Pipeline Integration
  33. Build Script Integration
  34. Complete Local Workflow
  35. Error Handling
  36. Migration from v4
  37. Breaking Changes
  38. Migration Steps
  39. Why v5 is better
  40. Generated Output
  41. Input Structure
  42. Generated Output
  43. Key Features

OneKey

A local translation management utility with AI translation support and TypeScript key generation. OneKey provides a complete local-only workflow for managing translations with state tracking, AI-powered translation, and type-safe internationalization.

Installation

npm install @guestlinelabs/onekey

Table of Contents

CLI Usage

OneKey provides a local-only translation workflow with state tracking:

Initialize translation state

Sets up local state tracking for translation freshness management. This is the first command you should run when setting up a new translation project.

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

What it does:

  • Scans your base locale translation files
  • Creates oneKeyState.json with timestamp tracking for all translation keys
  • Sets up the foundation for translation freshness tracking
  • Configures automatic generation of translation.ts (can be disabled with --no-generate-keys)

Example:

onekey init -p ./translations -l en
onekey init -p ./translations --no-generate-keys

Sync translation state

Synchronizes the translation state, generates TypeScript keys, and reports stale translations.

Usage: onekey sync [options]

What it does:

  • Initializes new untracked keys and languages
  • Generates translation.ts (unless disabled in init)
  • Reports keys where translations are stale (base locale newer than translated locale)
  • Reports missing translations
  • Exits with code 1 if issues are found

Example:

onekey sync

Check translation status

Read-only check for stale or missing translations (perfect for CI/CD).

Usage: onekey status [options]

What it does:

  • Loads oneKeyState.json and compares timestamps across locales
  • Reports keys where translations are stale (base locale newer than translated locale)
  • Reports missing translations
  • Never modifies state or generates files
  • Exits with code 1 if issues are found (perfect for CI/CD)

Example:

onekey status

Translate with AI

Uses AI to automatically translate your content into different languages with intelligent state tracking. Only translates stale or missing translations by default.

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

State-Aware Translation:

  • Only translates keys that are stale (base locale newer than target locale)
  • Automatically updates state timestamps after successful translations
  • Use --updateAll to force re-translation of all keys
  • Use --stats to see how many stale keys exist per locale

Context File Support:

  • Provide a text file with additional context to improve translation quality
  • Example: "These translations are used in a booking engine for hotel rooms"

Translation Tones:

  • formal - Polite and professional language
  • informal - Casual and friendly language
  • neutral - Balanced tone (default)

Environment Variables:

  • OPENAI_API_URL - OpenAI API endpoint (fallback for --apiUrl)
  • OPENAI_API_KEY - OpenAI API key (fallback for --apiKey)
  • OPENAI_API_MODEL - OpenAI API model (fallback for --apiModel)

Local State Tracking

OneKey uses a local oneKeyState.json file to track translation freshness and manage the translation workflow without external dependencies.

State File Structure

The oneKeyState.json file is created in your translations directory and tracks when each translation key was last modified:

{
  "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" }
    }
  }
}

Key Features

  • Namespaced Keys: Keys are flattened with namespace prefixes (e.g., main.hello, errors.validation.required)
  • Timestamp Tracking: ISO-8601 timestamps for precise modification tracking
  • Stale Detection: Automatically identifies when base locale is newer than translations
  • Missing Translation Detection: Reports keys that exist in base locale but not in target locales

Workflow

  1. Initialize: onekey init scans base locale and creates initial state
  2. Translate: onekey translate updates only stale translations and updates timestamps
  3. Check: onekey status reports current translation health
  4. Sync Again: run onekey sync anytime you want to regenerate translation.ts and refresh the state

Programmatic API

The library exports several functions for programmatic use in your Node.js applications:

State Management Functions

loadState(statePath, baseLocale)

Loads the translation state from a JSON file.

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

saveState(statePath, state)

Saves the translation state to a JSON file.

import { saveState } from "@guestlinelabs/onekey";

await saveState("./translations/oneKeyState.json", state);

touch(state, locale, key, date?)

Updates the timestamp for a specific translation key.

import { touch } from "@guestlinelabs/onekey";

touch(state, "en-GB", "main.hello", new Date());

isStale(state, baseLocale, locale, key)

Checks if a translation is stale (base locale newer than target locale).

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

diffState(state)

Generates a report of all stale translations.

import { diffState } from "@guestlinelabs/onekey";

const diffs = diffState(state);
// Returns array of { locale, key, baseTs, localeTs }

Core Functions

generateKeys(options)

Generates TypeScript type definitions from translation files.

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

translate(options)

Translates content using AI with state tracking.

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
});

File Operations

saveKeys(options)

Saves generated TypeScript keys to a file.

import { saveKeys } from "@guestlinelabs/onekey";

await saveKeys({
  translationsPath: "./translations",
  translationKeysPath: "./src/types",
  defaultLocale: "en-GB",
  prettierConfigPath: "./.prettierrc",
});

saveAiTranslations(options)

Translates and saves content using AI with state tracking.

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
});

initializeState(options)

Initializes state tracking for a translation project.

import { initializeState } from "@guestlinelabs/onekey";

await initializeState({
  translationsPath: "./translations",
  baseLocale: "en-GB",
});

checkStatus(options)

Checks translation status and returns exit code.

import { checkStatus } from "@guestlinelabs/onekey";

const exitCode = await checkStatus({
  translationsPath: "./translations",
});

console.log(exitCode); // 0 if all good, 1 if issues found

Advanced Features

Local State Management

OneKey provides sophisticated local state tracking:

  • Timestamp Precision: ISO-8601 timestamps for accurate freshness tracking
  • Namespaced Keys: Flattened key structure with namespace prefixes
  • Stale Detection: Intelligent comparison of modification times across locales
  • Missing Translation Detection: Identifies keys that exist in base but not target locales

Translation Chunking

For large translation files, the AI translation feature automatically:

  • Splits Large Files: Breaks translations into chunks of 100 keys
  • Parallel Processing: Processes multiple chunks concurrently
  • Memory Optimization: Prevents API timeouts and memory issues
  • State Updates: Updates timestamps only after successful translations

Hierarchical JSON Support

Supports nested translation structures:

{
  "user": {
    "profile": {
      "name": "Name",
      "email": "Email"
    }
  }
}

Generates flattened keys like: "main.user.profile.name", "main.user.profile.email"

Language Code Normalization

The library automatically maps common language codes to their full locale identifiers:

// Automatic mapping
'es' → 'es-ES'
'fr' → 'fr-FR'
'de' → 'de-DE'
'en' → 'en-GB'
// And more...

Retry Logic and Error Handling

  • Exponential Backoff: Automatic retry with increasing delays for failed API requests
  • Configurable Retries: Up to 3 retry attempts with 5-second delays
  • Graceful Degradation: Continues processing other files when individual files fail
  • State Consistency: Only updates state after successful operations

Configuration Options

Prettier Integration

All file operations support Prettier formatting:

// Automatic prettier config detection
await saveKeys({
  // ... other options
  prettierConfigPath: "./.prettierrc.json",
});

Environment Variables

The library supports these environment variables:

  • OPENAI_API_URL - OpenAI API endpoint
  • OPENAI_API_KEY - OpenAI API key

Project Structure

Expected directory structure:

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

State File Format

The oneKeyState.json file structure:

{
  "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" }
    }
  }
}

TypeScript Integration

Generated Types

The library generates comprehensive TypeScript types:

// 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;
};

Parameter Extraction

Automatically detects and types translation parameters:

{
  "welcome": "Hello, {{name}}!",
  "items": "You have {{count}} items"
}

Generates:

type TranslationWithOptions = {
  "main:welcome": { name: string };
  "main:items": { count: number }; // 'count' is typed as number
};

Usage in Applications

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

Examples and Best Practices

CI/CD Pipeline Integration

# .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

Build Script Integration

{
  "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"
  }
}

Complete Local Workflow

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!");
}

Error Handling

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);
}

Migration from v4

OneKey v5 fully removes OneSky integration and introduces local-only state tracking. Use this guide to upgrade existing v4 projects.

Breaking Changes

  • OneSky removed – The fetch, upload, and check CLI commands (and their corresponding APIs) are gone. All translations now live exclusively in your repository.
  • Local state file required – A new oneKeyState.json file (created by onekey init) stores per-key timestamps so OneKey can tell when translations are stale or missing.
  • New core commands – init, sync, and status replace generate and check, adding automatic state management. The translate command is now state-aware and adds flags like --update-all, --stats, --api-model, etc.
  • Environment variables changed – Remove ONESKY_PRIVATE_KEY and ONESKY_PUBLIC_KEY. Keep OPENAI_API_URL, OPENAI_API_KEY, and optionally OPENAI_API_MODEL.
  • API surface updated – OneSky functions (fetchTranslations, upload, checkTranslations, saveOneSkyTranslations) were removed. New helpers (initializeState, syncState, checkStatus, loadState, saveState, touch, isStale, diffState) are available.

Migration Steps

  1. Initialise local state

    onekey init -p ./translations -l en-GB
    
  2. Update your scripts

    v4 commandv5 replacement
    onekey generateonekey sync
    onekey checkonekey status
    onekey fetch— (removed)
    onekey upload— (removed)
  3. Clean environment variables

    unset ONESKY_PRIVATE_KEY
    unset ONESKY_PUBLIC_KEY
    # keep your OpenAI variables
    export OPENAI_API_KEY=your-key
    
  4. Migrate programmatic usage

    - import { fetchTranslations, upload, checkTranslations } from "@guestlinelabs/onekey";
    + import { initializeState, syncState, checkStatus, translate } from "@guestlinelabs/onekey";
    

    Typical v5 flow:

    await initializeState({
      translationsPath: "./translations",
      baseLocale: "en-GB",
    });
    await syncState();
    await translate({ path: "./translations", stats: true });
    
  5. Verify – Run onekey status. Exit code 0 means everything is up-to-date; 1 indicates stale or missing translations.

Why v5 is better

  • Zero external dependencies – no calls to OneSky.
  • Faster incremental AI translation – only changed keys are processed.
  • Simple CI checks with onekey status.

Generated Output

The generate command creates comprehensive TypeScript type definitions from your translation files.

Input Structure

// 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"
  }
}

Generated Output

// 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;
};

Key Features

  • Locale Management: Complete locale definitions with ISO mappings
  • Namespace Support: Organized by translation file names
  • Parameter Typing: Automatic detection of {{variable}} patterns
  • Special Handling: count parameters are typed as number
  • Nested Keys: Support for hierarchical JSON structures with dot notation
  • Type Safety: Full TypeScript integration with compile-time validation

版本与发布记录

@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 是什么?

Local translation management utility with AI translation support and TypeScript key generation

如何安装 @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 和提交记录判断。