Pseudoloc v1.2.1

Pseudoloc 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.

Using with Node.js

var pseudoloc = require('pseudoloc');

pseudoloc.str('A test string with a %token%.')
// [!!Á ţȇšŧ śťřīņğ ŵıţħ ą %token%.!!]

Using in a browser

<script src="../pseudoloc.js" type="text/javascript"></script>
<script type="text/javascript">

  pseudoloc.str('A test string with a %token%.')
  // [!!Á ţȇšŧ śťřīņğ ŵıţħ ą %token%.!!]

</script>

Using from the commandline

Pseudoloc includes a commandline 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. Each of the value in the file that is a string will then be pseudolocalized.

Note: Nodejs must be installed to use the commandline interface.

node ./bin/pseudoloc --string 'A test string with a %token%.'
// [!!Á ţȇšŧ śťřīņğ ŵıţħ ą %token%.!!]


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

node ./bin/pseudoloc -readFile example.json -writeFile example-pseudo.json

// example-pseudo.json
{
  "string1": "[!!ţĥıś ıś ţĥę ƒıŕśţ śţŕıńĝ!!]",
  "string2": "[!!ȃ šŧřįƞģ ŵįŧħ ȃ %token%!!]",
  "string3": "[!!à śţŕīńĝ ŵīţĥ à %couple% ōƒ %tokens%!!]",
  "obj1": {
    "string1": "[!!ţĥıś ıś ţĥę ƒıŕśţ śţŕıńĝ!!]",
    "string2": "[!!ȃ šŧřįƞģ ŵįŧħ ȃ %token%!!]",
    "string3": "[!!à śţŕīńĝ ŵīţĥ à %couple% ōƒ %tokens%!!]"
  }
}

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

node ./bin/pseudoloc --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 [!!.

pseudoloc.option.prepend = '[##';
pseudoloc.str('A test string with a %token%.')
// [##Á ţȇšŧ śťřīņğ ŵıţħ ą %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 !!].

pseudoloc.option.append = '##]';
pseudoloc.str('A test string with a %token%.')
// [!!Á ţȇšŧ śťřīņğ ŵıţħ ą %token%.##]

Delimiter, StartDelimiter, EndDelimiter, Delimiters

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 %.

pseudoloc.option.delimiter = '$$';
pseudoloc.str('A test string with a $$token$$.')
// [!!Á ţȇšŧ śťřīņğ ŵıţħ ą $$token$$.!!]

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

If you need to support multiple types of delimiters, you can pass an array of delimiters (single or pairs) to the delimiters option.

The delimiters option takes an array of objects. Set properties on the objects as follows:

{ start, end }: specifies a pair of start and end delimiters, just like using startDelimiter and endDelimiter:
```
{ start: '<', end: '>' }
```
{ both }: specifies a marker to use as both the start and end delimiters, just like using delimiter
```
{ both: '$$' }
```
{ full }: specifies the entire pattern for the delimiter. This is useful for cases where the token doesn't have a start marker, name, and end marker, for example with printf-style placeholders %s, %d, etc.
```
{ full: '%d' }
```

Under the hood these strings are combined into a pattern that eventually is compiled into a RegExp. That can affect you in a couple of ways:

You can use regular expression matchers in your delimiters
If your delimiter includes any characters that are special characters in regular expressions, they will need to be escaped

For example, to match named sprintf-style placeholders (such as %(name)s), you need to escape the parentheses:

// Note the double-backslash, which becomes a `\(` in the string
pseudoloc.option.startDelimiter = '%\\(';
// Note the square brackets, so it matches `)s` or `)d`
pseudoloc.option.endDelimiter = '\\)[sd]';
pseudoloc.str('A test string with a %(token)s.');
// [!!Á ţȇšŧ śťřīņğ ŵıţħ ą %(token)s.!!]

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. We extend the string by randomly selecting characters from a predefined array of non-ASCII characters.

Default is 0.

pseudoloc.option.extend = 0.3; //30%
pseudoloc.str('A test string with a %token%.')
// [!!Ȃ ťēšť ŝťŕĩŉğ ŵĩťħ â %token%. öఛฒそ!!]

New update: Extends the width of the string by the specified percentage will be filled with predefined array of non-ASCII characters.

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 pseudolocalization.

Default is undefined.

pseudoloc.option.override = '_';
pseudoloc.str('A test string with a %token%.')
// [!!_____________________%token%_!!]

Installation

Using npm:

$ npm install pseudoloc-js

Building

To build the javascript files for pseudoloc, run npm install to install dependencies and then:

$ npm run build

Making minified build

To build the minified javascript files for pseudoloc, run npm install to install dependencies and then:

$ npm run minify

Running tests

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

$ npm run test

Running benchmarks

To run the benchmarks for pseudoloc, run npm install to install dependencies and then:

$ npm run benchmark

jacalata/pseudoloc