Node.js Integration

Call the translation engine directly from your own scripts with @shipi18n/core.

View on GitHub View on npm

Features

The same engine every other package is built on

Structure-preserving JSON translation

Placeholder extraction and validation

Incremental translation via an existing map

Any provider through a { complete } adapter

Prerequisites

1.Node.js 18 or newer
2.An Anthropic or OpenAI API key of your own

Installation

npm install @shipi18n/core @anthropic-ai/sdk

# or, for OpenAI
npm install @shipi18n/core openai

Configuration

Set your own LLM key in the environment. It is read at translation time and never written to disk or sent anywhere except your provider:

# .env — never commit this
ANTHROPIC_API_KEY=your-key-here

Use OPENAI_API_KEY instead if you pass --provider openai.

Usage

const { result } = await translateJSON({ content, from: 'en', to: 'es' })

Examples

Translate an object

import { translateJSON } from '@shipi18n/core'

const { result, stats } = await translateJSON({
  content: { greeting: 'Hello {{name}}' },
  from: 'en',
  to: 'es',
  provider: 'anthropic',
})

console.log(result) // { greeting: 'Hola {{name}}' }
console.log(stats)  // { translated, reused, placeholderWarnings }

Reuse existing translations

const { result } = await translateJSON({
  content: source,
  from: 'en',
  to: 'fr',
  provider: 'anthropic',
  existing: previousFrench,   // only new or empty keys are sent
})

Bring any model

const myAdapter = {
  name: 'my-llm',
  async complete(prompt) {
    // call your model however you like, return its text
    return await callMyModel(prompt)
  },
}

await translateJSON({ content, from: 'en', to: 'de', provider: myAdapter })

Best Practices

Pass existing on every run so you only pay for what actually changed.
Check stats.placeholderWarnings and fail your build on a non-empty result. Each entry is { path, source, translation, ok, missing, added }.
Run it at build or release time, never in a request handler — it is a batch operation.

Troubleshooting

The 'anthropic' provider requires the '@anthropic-ai/sdk' package

The provider SDKs are optional peer dependencies so you only install the one you use. Run npm install @anthropic-ai/sdk (or openai).

Cannot use import statement outside a module

@shipi18n/core is ESM. Use "type": "module" in package.json, an .mjs file, or a dynamic import() from CommonJS.

Need help? Read the docs

View on GitHub