pseudolocale

What is pseudolocale?

The pseudolocale npm package is used to generate pseudolocalized versions of strings for testing internationalization (i18n) in software applications. Pseudolocalization helps developers identify potential issues with string length, character encoding, and layout before actual translation work begins.

What are pseudolocale's main functionalities?

Basic Pseudolocalization

This feature allows you to convert a simple string into its pseudolocalized version. The pseudolocalized string will have additional characters and accents to simulate the appearance of translated text.

const pseudolocale = require('pseudolocale');
const originalString = 'Hello, world!';
const pseudolocalizedString = pseudolocale.str(originalString);
console.log(pseudolocalizedString);

Custom Pseudolocalization

This feature allows you to customize the pseudolocalization process by adding specific characters or strings before and after the original text. This can help simulate different localization scenarios.

const pseudolocale = require('pseudolocale');
pseudolocale.option.prepend = '>>';
pseudolocale.option.append = '<<';
const originalString = 'Hello, world!';
const pseudolocalizedString = pseudolocale.str(originalString);
console.log(pseudolocalizedString);

Pseudolocalize JSON Objects

This feature allows you to pseudolocalize all string values within a JSON object. This is useful for testing the localization of entire data structures.

const pseudolocale = require('pseudolocale');
const originalObject = { greeting: 'Hello, world!', farewell: 'Goodbye!' };
const pseudolocalizedObject = {};
for (const key in originalObject) {
  pseudolocalizedObject[key] = pseudolocale.str(originalObject[key]);
}
console.log(pseudolocalizedObject);

Other packages similar to pseudolocale

fluent

Fluent is a localization system designed to improve how software is translated. It focuses on natural language and allows for more complex translations. Unlike pseudolocale, Fluent is more about actual localization rather than pseudolocalization for testing purposes.

i18next

i18next is a popular internationalization framework for JavaScript. It provides a complete solution for localizing applications, including translation management and language detection. While i18next focuses on real translations, pseudolocale is specifically for generating pseudolocalized text for testing.

react-intl

react-intl is a library for internationalizing React applications. It provides components and API for formatting dates, numbers, and strings, and handling pluralization. Unlike pseudolocale, react-intl is used for actual localization rather than pseudolocalization.

README

Pseudolocale

Pseudolocale is a small library for quickly pseudolocalizing strings. Pseudolocalization is a method for testing the internationalization aspects of your application by replacing your strings with altered versions that maintains string readability while including the most problematic characteristics including text length and character length. It also makes hard coded strings and improperly concatenated strings easy to spot so that they can be properly localized. This library is idempotent eg. it always creates the same string.

Installation

npm install pseudolocale
# or
yarn add pseudolocale

Using with Node.js

const pseudolocale = require('pseudolocale');

// or using ESM
import pseudolocale from 'pseudolocale';

pseudolocale('This is going to be pseudolocalized %token%.');
// [!!Ţĥĩś ĩś ĝōĩńĝ ţō ƀē ƥśēũďōĺōćàĺĩźēď %token%.!!]

Using from the command line

Pseudolocale includes a command line interface to make it easy to incorporate it into your build process. Currently it supports passing in individual strings (great for trying things out) or passing in a valid JSON document that contains a set of keys and strings. Each of the strings in the file will then be pseudolocalized.

Note: Nodejs must be installed to use the command line interface.

pseudolocale --string 'This is going to be pseudolocalized %token%.'
# [!!Ţĥĩś ĩś ĝōĩńĝ ţō ƀē ƥśēũďōĺōćàĺĩźēď %token%.!!]

example.json

{
  "string1": "this is the first string",
  "string2": "a string with a %token%",
  "string3": "a string with a %couple% of %tokens%"
}

pseudolocale --readFile example.json --writeFile example-pseudo.json

example-pseudo.json

{
  "string1": "[!!ţĥĩş ĭś ťĥě ƒĩŗśŧ şţřįƞĝ!!]",
  "string2": "[!!ȁ ŝťŗĩňğ ŵįťĥ ã %token%!!]",
  "string3": "[!!ȃ şťřīňğ ŵĩťħ ä %couple% ŏƒ %tokens%!!]"
}

The command line tool uses the same options as the library. For additional help and more examples:

pseudolocale --help

Options

Prepend

Specifies the string that should be prepended to the beginning of pseudolocalized strings. The prepended and appended strings help to locate strings that have been cut off or improperly concatenated together - localized strings should use tokens for data since different languages have different word orders.

Default is [!!.

pseudolocale('This is going to be pseudolocalized %token%.', {
  prepend: '[##',
});
// [##Á ţȇšŧ śťřīņğ ŵıţħ ą %token%.!!]

Append

Specifies the string that should be appended to the end of pseudolocalized strings. The prepended and appended strings help to locate strings that have been cut off or improperly concatenated together - localized strings should use tokens for data since different languages have different word orders.

Default is !!].

pseudolocale('This is going to be pseudolocalized %token%.', { append: '##]' });
// [!!Á ţȇšŧ śťřīņğ ŵıţħ ą %token%.##]

Delimiter, StartDelimiter, EndDelimiter

Specifies the token delimiter. Any characters between token delimiters will not be pseudolocalized. Tokens are used to replace data within localized strings. You can either specify a single delimiter or use startDelimiter and endDelimiter to specify the delimiters seperately.

Default is %.

pseudolocale('A test string with a $$token$$.', { delimiter: '$$' });
// [!!Á ţȇšŧ śťřīņğ ŵıţħ ą $$token$$.!!]

pseudolocale('A test string with a {{token}}.', {
  startDelimiter: '{{',
  endDelimiter: '}}',
});
// [!!Á ţȇšŧ śťřīņğ ŵıţħ ą {{token}}.!!]

Extend

Extends the width of the string by the specified percentage. Useful if you will be localizing into languages such as German which can be 30% longer than English.

Default is 0.

pseudolocale('This is going to be pseudolocalized %token%.', { extend: 0.3 }); // 30%
// [!!Ȃ ťēšť ŝťŕĩʼnğ ŵĩťħ â %token%.        !!]

Override

Specifies an override character that all characters in the string will be replaced with. Used to easily spot unlocalized strings. Set to undefined to go back to regular pseudolocalealization.

Default is undefined.

pseudolocale('This is going to be pseudolocalized %token%.', { override: '_' });
// [!!_____________________%token%_!!]

Contribution

Installation

Using npm:

npm i

Building

To build javascript files for pseudolocale, run npm i to install dependencies and then:

npm run build

Running tests

To run the tests for pseudolocale, run npm i to install dependencies and then:

npm test

Release new version

1. change version in package.json

2. Publish to npm

npm login
npm publish

1. Push package.json & package-lock.json to origin.
2. Go to GitHub releases https://github.com/MartinCerny-awin/pseudolocale/releases and create new release