npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

translate

v3.0.1

Published

Translate text to different languages on node.js and the browser

Downloads

25,380

Readme

Translate npm install translate test badge gzip size

Convert text to different languages on Node.js and the browser. Flexible package that allows you to use Google (default), Yandex, Libre or DeepL:

import translate from "translate";

translate.engine = "deepl";
translate.key = process.env.DEEPL_KEY;

const text = await translate("Hello world", "es");
console.log(text);
// "Hola mundo"

Getting started

This package can be used in Node.js and on the browser. First thing install the library:

npm install translate

Then import it to use it:

import translate from "translate";

Alternatively for the browser you can use Jsdelivr CDN with the UMD export:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/translate/index.min.js"
></script>

After including translate the usage is similar for both Node.js and the browser. Now you have to set which engine you want to use (default is 'google'), and the key for it if needed:

translate.engine = "deepl"; // "google", "yandex", "libre", "deepl"
translate.key = process.env.DEEPL_KEY;

Then you can use it. Putting it all together:

// Omit this line if loading from a CDN
import translate from "translate";

translate.engine = "deepl"; // "google", "yandex", "libre", "deepl"
translate.key = process.env.DEEPL_KEY;

const text = await translate("Hello world", "es");
console.log(text);
// "Hola mundo"

Options

Here is a list of all the options. They all can be set on the root instance like translate[key] = value and when creating a new instance const t = Translate({ ... }). The function has this signature:

translate(text: string, to: string): Promise<string>
translate(text: string, { to: string, from: string }): Promise<string>

These are all of the options:

  • to: the string of the language to translate to. It can be in any of the two ISO 639 (1 or 2) or the full name in English like Spanish. Defaults to en.
  • from: the string of the language to translate to. It can be in any of the two ISO 639 (1 or 2) or the full name in English like Spanish. Also defaults to en.
  • cache *: a Number with the milliseconds that each translation should be cached. Leave it undefined to cache it indefinitely (until a server/browser restart).
  • engine * (& engines): a String containing the name of the engine to use for translation. Right now it defaults to google. Read more in the engine section.
  • key * (& keys): the API Key for the engine of your choice. Read more in the engine section.
  • url *: only available for those engines that you can install on your own server (like Libretranslate), allows you to specify a custom endpoint for the translations. See this issue for more info.

* The options marked as can only be set to the root translate.cache = 1000 or when creating a new instance const myDeepL = translate.Translate(), but not as the second parameter.

Examples:

// Translate from English (default) to Spanish (specified)
const foo = await translate("Hello world", "es");

// Same as this:
const bar = await translate("Hello world", { to: "es" });

Default options

You can change the options in 3 ways. First, for the simple from and to options, set them as the second argument:

import translate from "translate";

translate("Hello world", "es");
translate("Hola mundo", { from: "en", to: "es" });

You can also change the default options straight on the base instance, which should be common for the shared options such as the API key, engine, etc:

import translate from "translate";

// Configure it, setting the "from" to "Spanish" as default!
translate.from = "es";
translate.engine = "deepl";
translate.key = process.env.DEEPL_KEY;

// Use it
await translate("Hola mundo", "ja");

Finally, you can combine multiple instances of Translate, which is useful to have different caches, or use different engines at the same time:

// Import the constructor
import { Translate } from 'translate';

// Create an instance
const myLib = Translate({ engine: 'deepl', from: 'es', ... });

// Use it
await myLib("Hola mundo", "ja" );

Engines

Several translating engines are available to translate your text:

  • google: (demo | docs): Google Translate.
  • yandex: (demo | docs | API Key): Yandex Translate
  • libre: (demo): An independent translation engine. You can use the official website or install it on your own server.
  • deepl: (demo): A rapidly growing popular translation engine built with Machine Learning.

To get the API Key you will be signing some contract with these services; it's your responsibility to follow these and we are not liable if you don't as explained in our MIT License.

Once you get the API key and if you are only going to be using one engine (very likely), we recommend setting this globally for your whole project:

import translate from "translate";

translate.engine = "deepl";
translate.key = "YOUR-KEY-HERE";

// ... use translate()

If you are in Node.js, this likely comes from an environment variable:

import translate from "translate";

translate.engine = "deepl";
translate.key = process.env.TRANSLATE_KEY;

// ... use translate()

You can create different instances if you want to combine different engines:

import { Translate } from "translate";

const gTranslate = Translate({ engine: "google", key: "..." });
const dTranslate = Translate({ engine: "deepl", key: "..." });
const lTranslate = Translate({ engine: "libre", key: "..." });

Specifically in Libretranslate, you can also add a url parameter if you install it on your own server:

translate.url = "https://example.com/";
translate.key = process.env.TRANSLATE_KEY;

// or

const lTranslate = Translate({
  engine: "libre",
  url: "...",
  key: "YOUR-KEY-HERE",
});

Promises

This library uses promises which need to be awaited for the translated result:

// Browser; jQuery for demonstration purposes
$("#translate").submit(async (e) => {
  e.preventDefault();
  const text = $(".text").text();
  const spanish = await translate(text, { to: "es" });
  alert(spanish);
});

// Node.js; serverjs.io example for demonstration purposes
const route = async (ctx) => {
  const spanish = await translate(ctx.body, { to: "es" });
  return send(spanish);
};

Authors and thanks

Current package and development: Francisco Presencia

Original package and idea: Andrew Lunny (alunny), Marak Squires, Google

Testing in Internet Explorer supported by BrowserStack:

BrowserStack logo