Plurr

Cross-platform format specification + libraries for handling plurals/genders/conditionals for Go, Java, JS, Obj-C, Perl, PHP, Python, and Rust
Alternatives To Plurr
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
String Format2967165115 years ago6May 18, 20189otherJavaScript
JavaScript string formatting inspired by Python’s `str.format()`
Maven Git Versioning Extension281
a month ago100August 22, 20238gpl-3.0Java
This extension will set project version, based on current Git branch or tag.
Codable Diy Kit197
4 years ago2mitSwift
A template for creating your own Swift Codable encoders and decoders
Format Message194951212 years ago45February 17, 202217mitJavaScript
Internationalization Made Easy
Gradle Git Versioning Plugin91
a month ago8gpl-3.0Java
This extension will set project version, based on current Git branch or tag.
Muso86
2 years ago2gpl-3.0Rust
muso: music sorter
Plurr75
3 years ago1February 01, 20215mitRust
Cross-platform format specification + libraries for handling plurals/genders/conditionals for Go, Java, JS, Obj-C, Perl, PHP, Python, and Rust
Icu Message Format For Translators74
5 years agoHTML
Instructions for translators using the ICU Message Format
Fomatto486789 years ago2March 04, 20115mitJavaScript
JavaScript string interpolation and formatting.
Rsstail.py42
a year ago11August 11, 20187otherPython
A command-line syndication feed monitor
Alternatives To Plurr
Select To Compare


Alternative Project Comparisons
Readme

About Plurr

Handling plurals, genders and conditionals in strings is not a particularly favorite task for programmers for many reasons. There's no common agreement on how to handle such variants, so all existing approaches are either platform-specific (like gettext/po), or have limitations (for example you can't have multiple plurals in one string), or not particularly translator- friendly, like Java's MessageFormat/ChoiceFormat.

Plurr is a universal format specification for handling plurals, genders, conditionals and placeholders designed to be easy to support for developers and understandable for translators yet robust to support different language requirements. Plurr formatters are implemented in: Go, Java, JavaScript, Objective-C, Perl, PHP, Python, and Rust. Feel free to contribute to this project and provide support for your favorite languages.

Try the live demo →

Advantages

  1. You can use Plurr with any L10N library of your choice: you can store and read Plurr-formatted messages the same way as you do for any other strings.
  2. Same string format across multiple languages means that strings can be reused more effectively. This all reduces the time and cost of translation.
  3. Named placeholders provide a great context for translators, and this means better translation quality.
  4. Named placeholders allow to change their order in the final string if this is more appropriate for a particular target language.
  5. Less programmatic string concatenation also helps understand the message as a whole.

Syntax Example

Do you want to delete {N_PLURAL:this {N} file|these {N} files} permanently?

Which, depending on the provided N value, will render as (for English):

  • N = 1, N_PLURAL = 0: Do you want to delete this 1 file permanently?
  • N = 5, N_PLURAL = 1: Do you want to delete these 5 files permanently?

The value of N_PLURAL is determined by calling a plural() function with the value of N, and is language-dependent. By default, plurals are calculated automatically: when FOO_PLURAL placeholder is found and its value is not provided to the formatting function, Plurr will try to do FOO_PLURAL = plurals(FOO) internally, taking into consideration the current locale defined for the Plurr object. Below is a sample JavaScript code:

var p = new Plurr();  // create a Plurr object (once). Default locale is English
...
alert(p.format(
  "Do you want to delete {N_PLURAL:this {N} file|these {N} files} permanently?",  // message
  {'N': 5}  // parameters
));

The syntax itself is not something new, it is similar to the one used in the already mentioned Java's MessageFormat, but it is minimalistic and contains no sensitive words that translators can inadvertently change (and break).

Format specification

1. Simple named placeholders

Format

{NAME}

Example

{FOO} and {BAR}

Here {FOO} will be substituted with the provided FOO value, and {BAR} with the value of BAR.

Recommended is the use of capital A..Z and _ symbol this makes placeholders stand out in the text, which gives some additional clue to translators that these sequences are something special and should not be translated.

There are no restrictions on placeholder names, except that they must not contain } or : symbol.

When you need to represent symbols { or } themselves in the final string, replace them with named placeholders with corresponding values, for example:

alert(p.format(
  "I love {<}curly{>} braces.",
  {
    '<': '{',
    '>': '}'
  }
));

2. Placeholders with alternatives

{CHOICE:FORM0[|FORM1][|FORM2][|FORM3][|...]}

where:

  • CHOICE is a zero or a positive integer.
  • FORM0, FORM1 and so on are the alternative versions of the string for each value of CHOICE (starting from 0).

If less forms are provided than the value of CHOICE, the last form is used.

As | is used to delimit different alternatives, in order to display such symbol in the final string, replace it with named placeholder with the corresponding value (same as for { and } in the section above).

Example in English:

{N_PLURAL:{N} file|{N} files}

will render as:

  • N = 0, N_PLURAL = 1: 0 files
  • N = 1, N_PLURAL = 0: 1 file
  • N = 2, N_PLURAL = 1: 2 files
  • N = 5, N_PLURAL = 1: 5 files

Example of the same string translated into Russian:

{N_PLURAL:{N} |{N} |{N} }

will render as:

  • N = 0, N_PLURAL = 2: 0
  • N = 1, N_PLURAL = 0: 1
  • N = 2, N_PLURAL = 1: 2
  • N = 5, N_PLURAL = 2: 5

3. Multiple placeholders in the same string

Inside a string, there can be multiple placeholders of any kind.

Example:

{X_PLURAL:{X} file|{X} files} found in {Y_PLURAL:{Y} folder|{Y} folders}.
Do you want to {COMMAND:copy|move|delete} {X:them|it|them}?

Here, in addition to handling plurals, we use a value of COMMAND placeholder to display different verbs.

Same example in Russian:

 {Y_PLURAL:{Y} |{Y} |{Y} } {X_PLURAL: {X} | {X} | {X} }.
 {X:|} {COMMAND:||}?

4. Handling genders

Handling genders is the same as handling any other type of placeholders. You just need to provide a parameter (let's name it GENDER), which evaluates to, say, 0 for male, 1 for female, and 2 in case the gender is unknown (the way you number genders is purely arbitrary, but we recommend sticking to some scheme that you use consistently across your application). Then all you need to do is to construct a message like this:

Do you want to leave {GENDER:him|her|them} a message?
{GENDER:He|She|They} will see it when {GENDER:he|she|they} {GENDER:logs|logs|log} in.

5. Nested placeholders and special cases

Sometimes one would like to say "One file" instead of "1 file", and "No files" instead of "0 files". That's (and other scenarios) are possible with nested placeholders:

{X:No files|One file|{X} {X_PLURAL:file|files}} found.

Here we first make a choice based on the value of X, where for values 0 and 1 we render special messages, and for values 2 and above we render the nested plural-aware placeholder.

Same example in Russian:

{X:  |  |{X_PLURAL: {X} | {X} | {X} |}}.

Such an approach allows translators to provide most natural translation possible, and gives some peace of mind to developers helping them reduce the amount of supporting if...else code in their applications.

Syntax Highlighting

Plurr also has a syntax highlighter available for CodeMirror, which is a part of the live demo.

Popular Format Projects
Popular Placeholder Projects
Popular Text Processing Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Javascript
Python
Java
Php
Golang
Rust
Objective C
Perl
Format
Placeholder
Russian