@guestlinelabs/onekey
Advanced tools
Local translation management utility with AI translation support and TypeScript key generation
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.
npm install @guestlinelabs/onekey
OneKey provides a local-only translation workflow with state tracking:
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:
oneKeyState.json with timestamp tracking for all translation keystranslation.ts (can be disabled with --no-generate-keys)Example:
onekey init -p ./translations -l en
onekey init -p ./translations --no-generate-keys
Synchronizes the translation state, generates TypeScript keys, and reports stale translations.
Usage: onekey sync [options]
What it does:
translation.ts (unless disabled in init)Example:
onekey sync
Read-only check for stale or missing translations (perfect for CI/CD).
Usage: onekey status [options]
What it does:
oneKeyState.json and compares timestamps across localesExample:
onekey status
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:
--updateAll to force re-translation of all keys--stats to see how many stale keys exist per localeContext File Support:
Translation Tones:
formal - Polite and professional languageinformal - Casual and friendly languageneutral - 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)OneKey uses a local oneKeyState.json file to track translation freshness and manage the translation workflow without external dependencies.
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" }
}
}
}
main.hello, errors.validation.required)onekey init scans base locale and creates initial stateonekey translate updates only stale translations and updates timestampsonekey status reports current translation healthonekey sync anytime you want to regenerate translation.ts and refresh the stateThe library exports several functions for programmatic use in your Node.js applications:
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
Saves the translation state to a JSON file.
import { saveState } from "@guestlinelabs/onekey";
await saveState("./translations/oneKeyState.json", state);
Updates the timestamp for a specific translation key.
import { touch } from "@guestlinelabs/onekey";
touch(state, "en-GB", "main.hello", new Date());
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
Generates a report of all stale translations.
import { diffState } from "@guestlinelabs/onekey";
const diffs = diffState(state);
// Returns array of { locale, key, baseTs, localeTs }
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
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
});
Saves generated TypeScript keys to a file.
import { saveKeys } from "@guestlinelabs/onekey";
await saveKeys({
translationsPath: "./translations",
translationKeysPath: "./src/types",
defaultLocale: "en-GB",
prettierConfigPath: "./.prettierrc",
});
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
});
Initializes state tracking for a translation project.
import { initializeState } from "@guestlinelabs/onekey";
await initializeState({
translationsPath: "./translations",
baseLocale: "en-GB",
});
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
OneKey provides sophisticated local state tracking:
For large translation files, the AI translation feature automatically:
Supports nested translation structures:
{
"user": {
"profile": {
"name": "Name",
"email": "Email"
}
}
}
Generates flattened keys like: "main.user.profile.name", "main.user.profile.email"
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...
All file operations support Prettier formatting:
// Automatic prettier config detection
await saveKeys({
// ... other options
prettierConfigPath: "./.prettierrc.json",
});
The library supports these environment variables:
OPENAI_API_URL - OpenAI API endpointOPENAI_API_KEY - OpenAI API keyExpected 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
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" }
}
}
}
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;
};
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
};
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
# .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);
}
OneKey v5 fully removes OneSky integration and introduces local-only state tracking. Use this guide to upgrade existing v4 projects.
fetch, upload, and check CLI commands (and their corresponding APIs) are gone. All translations now live exclusively in your repository.oneKeyState.json file (created by onekey init) stores per-key timestamps so OneKey can tell when translations are stale or missing.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.ONESKY_PRIVATE_KEY and ONESKY_PUBLIC_KEY. Keep OPENAI_API_URL, OPENAI_API_KEY, and optionally OPENAI_API_MODEL.fetchTranslations, upload, checkTranslations, saveOneSkyTranslations) were removed. New helpers (initializeState, syncState, checkStatus, loadState, saveState, touch, isStale, diffState) are available.Initialise local state
onekey init -p ./translations -l en-GB
Update your scripts
| v4 command | v5 replacement |
|---|---|
onekey generate | onekey sync |
onekey check | onekey status |
onekey fetch | — (removed) |
onekey upload | — (removed) |
Clean environment variables
unset ONESKY_PRIVATE_KEY
unset ONESKY_PUBLIC_KEY
# keep your OpenAI variables
export OPENAI_API_KEY=your-key
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 });
Verify – Run onekey status. Exit code 0 means everything is up-to-date; 1 indicates stale or missing translations.
onekey status.The generate command creates comprehensive TypeScript type definitions from your translation files.
// 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;
};
{{variable}} patternscount parameters are typed as numberFAQs
Local translation management utility with AI translation support and TypeScript key generation
The npm package @guestlinelabs/onekey receives a total of 572 weekly downloads. As such, @guestlinelabs/onekey popularity was classified as not popular.
We found that @guestlinelabs/onekey demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 11 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.
Security News
CISA’s 2025 draft SBOM guidance adds new fields like hashes, licenses, and tool metadata to make software inventories more actionable.