@kiritan/google-translate

English | 日本語

A Google Cloud Translation middleware for Kiritan. Plug it into translate.middlewares to have kiritan translate fill in missing and stale translations.

Install

npm install --save-dev @kiritan/google-translate

Usage

// .kiritanconfig
import { googleTranslate } from "@kiritan/google-translate";

export default {
  locales: { default: "en", list: ["en", "ja"] },
  sources: [{ glob: "base/README.base.md", strategy: "sidecar" }],
  translate: {
    auto: true,
    middlewares: [googleTranslate({ apiKey: process.env.GOOGLE_API_KEY })],
  },
};

With sidecar, the whole document goes to Google as one text and comes back as the translated sidecar file. With catalog, each :::kiritan{#id} block in the base file is translated separately — the base file needs those blocks, or there is nothing to translate.

Use googleTranslateBatch instead of googleTranslate to send many segments per request (up to 128 strings or 30k code points), which is much faster for a catalog source with lots of ids:

import { googleTranslateBatch } from "@kiritan/google-translate";

export default {
  // ...
  translate: {
    auto: true,
    middlewares: [googleTranslateBatch({ apiKey: process.env.GOOGLE_API_KEY })],
  },
};

Options

| Option | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------- | | apiKey | A Google Cloud API key with the Cloud Translation API enabled (required). | | baseUrl | Overrides the endpoint. | | languageCodes | Per-locale overrides of the language code sent as source/target, e.g. { zh: "zh-CN" }. Others go as-is. | | extraParams | Extra fields merged into the request body, e.g. { model: "nmt" }. | | retry | How many times to retry a failed request (network errors, 408/409/425/429/5xx). Default: 2. | | retryDelay | Delay between retries, in ms. Default: 500. | | timeout | Per-request timeout, in ms. Default: 30000. | | fetch | A custom fetch, for testing or a proxy. |

Behavior

• This uses the Basic (v2) API. Everything that must stay verbatim comes back untouched: code blocks, inline code, URLs, link destinations, HTML, front matter, :::kiritan{...} lines and %{name}. They are swapped for tokens before the text leaves your machine, wrapped in a <span translate="no"> (the text is sent as format: "html") so Google leaves them alone, and put back afterwards — and if Google drops one, the run fails instead of writing a translation that lost a link or a code span. (Built on @kiritan/middleware, so it also accepts its concurrency, minInterval, cache, protect, onError and onSkip options.)
• A text over Google's 30k code points (say a whole README for a sidecar translation) is split at paragraph boundaries and joined back with the original spacing. The wording around protected spans is up to Google, so review machine translations before publishing them — kiritan check flags catalog entries written this way as machine until you do.
• A failed request is retried (see retry) and then throws, and kiritan translate stops with Google's own message (an invalid key, an exhausted quota, ...).

Requirements

• Node.js >= 22.7 (HTTP goes through ofetch, its only dependency of note)

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

License

Distributed under the WTFPL License.