raven-writer

raven-writer is a FE utility to allow for easy translations and interpolations for projects using the popular POEditor localization service.

What raven-writer does:

• GETs and caches localizations for your project
• Refreshes those localizations at a given interval
• Transforms simple markdown in your content into HTML strings
• Allows for dynamic interpolation of string values into your content
• Easily gets values by term

---

Docs

• Installation
• Quick start example
• Instantiation - Creates the POE instance
  • POE.fetchLocalizations({...}) - Fetches and caches localizations
  • POE.makeDictionary(language) - returns a dictionary function
  • POE.localizations(language) - returns the raw localizations
  • POE.makeText(str, interpolations) - helper method to add interpolations to any string value and transform simple markdown into an HTML string
  • POE.kill() - Kills all refreshing of localizations on a POE instance
• Dictionary(term, interpolations) - function that returns the value from a cached language
• Content markdown and interpolation syntax - How your POEditor content should be written for MD and interpolations
• Localizations structure

Install

npm install raven-writer -S

Quick start example

Given the following POEditor project

In our project we have:

• A language that is American english, which has a ISO 639-1 language code of en-us
• A term MY_KEY that has a content value of "My value"
• A second term GREETING that has a content value of "Hello, **{{name}}!**"
  • Note that the value has {{}} to denote an interpolated value with the key name
  • It also has ** markdown indicating it should be bolded

import { Raven } from "raven-writer";

// make the POE instance
const POE = new Raven();

// load localizations into the instance
await POE.fetchLocalizations({
  id: "<POEDITOR_PROJECT_ID>",
  token: "<YOUR_READ_ONLY_POEDITOR_API_TOKEN>",
  languages: ["en-us"]
});

// make a dictionary
const Translate = POE.makeDictionary("en-us");

// Logs: "My value"
console.log(Translate("MY_KEY"));

// Logs: "Hello, <b>Nate!</b>"
console.log(Translate("GREETING", {name: "Nate"}));

Instantiation

In most cases you'll instantiate the POE instance simply by calling new Raven().

You can optionally pre-load the POE instance with localizations. You'd do this if you wanted access to the POE.makeDictionary(language) functionality without having to make API calls. Refer to the localizations structure if you want to do this.

Props

Prop	Type	Required?	Description
localizations	Object		The preloaded localizations

Returns

A POE instance that has the following methods:

POE.getLocalizations(localizations);
POE.fetchLocalizations({id, token, languages, keepAlive, url});
POE.makeDictionary(language);
POE.makeText(string, interpolations);
POE.kill();

Usage

Most common case

import { Raven } from "raven-writer";
const POE = new Raven();

Optional preloading

import { Raven } from "raven-writer";

const localizations = {
  "en-us": {
    "GREETING": "Hi!"
  }
};

const PRELOADED = new Raven(localizations);
const Translate = POE.makeDictionary("en-us");
console.log(Translate("GREETING")); // Logs: "Hi!"

POE.fetchLocalizations({...})

Fetches and catches localizations.

Props

Prop	Type	Required?	Description
token	String	if url is undefined	The readonly api_token found in your POEditor acct
id	String	if url is undefined	The project id found in your POEditor acct
languages	Array of ISO 639-1 language codes	if url is undefined	The languages you want to fetch for the given project
keepAlive	Integer		If present the localizations will be refreshed per milliseconds defined this value
url	String	if url, id, and languages are undefined	If present calls will be made to that url instead of hitting the POEditor endpoint

Returns

A promise that once resolved will populate the POE instance with localizations.

Usage

Most common usage

import { Raven } from "raven-writer";
const tenMins = 1000 * 60 * 10;
const POE = new Raven();
await POE.fetchLocalizations({
  id: "<POEDITOR_PROJECT_ID>",
  token: "<YOUR_READ_ONLY_POEDITOR_API_TOKEN>",
  languages: ["en-us", "sp_mx"],
  keepAlive: tenMins // optional
});

Overwriting the endpoint

import { Raven } from "raven-writer";
const POE = new Raven();
await POE.fetchLocalizations({
  url: "<YOUR_CUSTOM_GET_ENDPOINT>"
});

Note: the response from your endpoint must have the same structure as the localizations structure

POE.makeDictionary(language)

Makes a Dictionary function for a given language that has already been cached in the POE instance

Props

Prop	Type	Required?	Description
language	String	yes	A ISO 639-1 language code

Returns

A Dictionary function

Usage

import { Raven } from "raven-writer";
const POE = new Raven();
await POE.fetchLocalizations({..., languages: ["en-us", "sp-mx"]});
const enUsDictionary = POE.makeDictionary("en-us");
const spMxDictionary = POE.makeDictionary("sp-mx");

POE.getLocalizations(language)

Returns the raw localizations object. see: localizations structure.

Props

Prop	Type	Required?	Description
language	String	✅	A ISO 639-1 language code

Returns

A localizations object

Usage

Assume the cached localizations are the following:

{
  "en-us": {
    "GREETING": "Hello"
  },
  "sp-mx": {
    "GREETING": "Hola"
  }
}

import { Raven } from "raven-writer";
const POE = new Raven();
await POE.fetchLocalizations({..., languages: ["en-us", "sp_mx"]});
console.log(POE.getLocalizations()) // Logs the preceding full object
console.log(POE.getLocalizations("sp_mx")) // Logs { GREETING: "Hola" }

POE.makeText(str, interolations)

Adds interpolations and/or Markdown transformed into HTML string to a given string. See: Content markdown and interpolation syntax.

Props

Prop	Type	Required?	Description
str	String	✅	Any string value, ie not a POE term
interolations	Object		An object with key names that match the dynamic content markers in the str

Returns

A string with interpolations and Markdown transformed into HTML str (if applicable).

Usage

import { Raven } from "raven-writer";
const POE = new Raven();

// Logs: "Plain text"
console.log(POE.makeText("Plain text"));

// Logs: "Hello, Nate"
console.log(POE.makeText("Hello, {{name}}", { name: "Nate" }));

// Logs: "Some <i>italic text</i>"
console.log(POE.makeText("Some *italic text*"));

// Logs: "Hello, <b>Nate</b>"
console.log(POE.makeText("Hello, **{{name}}**", { name: "Nate" }));

POE.kill()

If you call POE.fetchLocalizations({...}) and set it to refresh localizations via keepAlive, this stops all refreshes on that instance.

Returns

undefined

Usage

import { Raven } from "raven-writer";
const tenMins = 1000 * 1000 * 60 * 10;
const POE = new Raven();
await POE.fetchLocalizations({..., keepAlive: tenMins});
...
POE.kill();

Dictionary(term, interpolations)

The function returns the localized content value of a term, optionally with injected interpolations. Markdown is transformed into HTML strings.

Props

Prop	Type	Required?	Description
term	String	✅	Any string value, ie not a POE term
interolations	Object		An object with key names that match the dynamic content markers for the content value associated with the term

Returns

A string with interpolations and Markdown transformed into HTML str (if applicable) for the language used to create the function.

Usage

import { Raven } from "raven-writer";

const POE = new Raven();
await POE.fetchLocalizations({..., languages: ["en-us", "sp-mx"]});

/*
Assume `POE.fetchLocalizations({...})` caches the following localizations:
{
  "en-us": {
    "GREETING": "*Hello*, {{name}}"
  },
  "sp-mx": {
    "GREETING": "Hola, {{name}}"
  }
}
*/

const EN_US = POE.makeDictionary("en-us");
const SP_MX = POE.makeDictionary("sp-mx");

// Logs: "<i>Hello</i>, Nate"
console.log(EN_US("GREETING", {name: "Nate"}));

// Logs: "Hola, Nate"
console.log(SP_MX("GREETING", {name: "Nate"}));

Content markdown and interpolation syntax

raven-writer supports a limited subset of markdown and a simple way of adding interpolations to your content. Use this as a guide when adding content values on the POEditor dashboard

Supported Markdown

Style	Markdown	Output
bold	**bold**	<b>world</b>
italic	*italic*	<i>italic</i>
bold italic	***bold italics***	<b><i>bold italic</i></b>
link	[link name](https://example.com)	<a href="https://example.com" target="_blank">link name</a>

Interpolations

Add variables into your content by using interpolations object. The keys in the interpolations object wrapped between {{ and }} can be used to represent dynamic content.

Localizations structure

The localizations are stored as a single nested object. Top level keys are ISO 639-1 language codes, each holding that language's localizations in key/value pairs where the key is what POEditor refers to as the term and value is what POEditor refers to as the content. See the POEditor API for more details.

Here is an example assuming 3 languages in the project with only one entry in each:

{
  "en-us": {
    "GREETING": "Hello"
  },
  "en-au": {
    "GREETING": "G'day"
  },
  "sp-mx": {
    "GREETING": "Hola"
  }
}