i18n4v

README

i18n for Virtual DOM (i18n4v)

$ npm install i18n4v --save

i18n4v is an internationalization helper library for browsers and node.js.

It has the following features:

• It supports standard internatinalization features:
  • Replacing words by key (original words can be used as keys too)
  • Pluralisation
  • Formatting
  • Selecting translations from context (like gender)
• Small runtime:
  • Runtime is written in ES3 and just 1.8kb (minified and gzipped)
  • Runtime library doesn't have any dependencies.
  • It is compatible with common.js and AMD and global reading with <script> tag.
• It can run on browser:
  • With virtual DOM (in JavaScript)
  • With static HTML text
• It can run on node.js:
  • To make off-line unittesting easy
  • To support server side rendering and CLI tools
• It provides CLI tool to maintain translations

Core part of i18n is derived from roddeh-i18n. Thank you roddeh.

Do you want to use Golang on your server? Yes! You can use Golang edition of this library. You can share same translation fileas between JavaScript and Golang.

Document

https://i18n4v.js.org/

Example

Use with JavaScript:

// This sample uses with Mithril.
// You can use any virtual DOM framework.
const m = require('mithril');
const i18n = require('i18n4v');

var mithrilComponent = {
    view(ctrl) {
        return m("div", i18n("hello world"));
    }
};

i18n.translator.add({
    values: {
        "hello world": "こんにちわ世界"
    }
});

Use with static HTML:

<article>
   <h1 data-i18n>Monty Python</h1>
</artice>
    
<script>
i18n.translator.add({
    values: {
        "Monty Python": "モンティ・パイソン"
    }
});
i18n.translator.applyToHTML();
</script>

License

MIT

Repository

https://github.com/shibukawa/i18n4v

Documentation

Overview

Package i18n4v provides i18n feature including pluralisation support, replacing kes, contextual translation to Golang. It is a member of https://i18n4v.js.org family. JavaScript runtime and this packages uses same translation format (JSON).

It supports translation via default translator instance or independent translator instances.

Default translator is good for command line tools. To use default translator, you can initialize via Add() function (and AddFromString(), MustAdd(), MustAddFromString()), and translate via global Translate() function.

Independent translator is good for web services, each client have their own preferred languages (in Accept-Language header). To use independent translator, you can create via Craete() function (and CreateFromString(), MustCreate(), MustCreateFromStrgin()), and translate via Translate() method of the instance.

The simplest translation is selecting words from language JSON:

i18n4v.MustAddFromString(`{
    "values": {
        "Cancel": "Cancelar"
    }
}`)

_ := i18n4v.Translate

_("Cancel")  // -> Cancelar

The following JSON provides pluralisation support. Each array contains matching pattern(minimum value and maximum value) and translation. null means math.MinInt64 or math.MaxInt64. %n and -%n are replaced with the number in parameter:

i18n4v.MustAddFromString(`{
    "values": {
        "%n comments": [
            [0, 0, "%n comments"],
            [1, 1, "%n comment"],
            [2, null, "%n comments"]
        ]
    }
}`)

_ := i18n4v.Translate

_("%n comments", 1)  // -> 1 comment

%{key} is replaced via replacement parameters. Parameter should be passed via Replace container (this is an alias of map[string]string):

_ := i18n4v.Translate

_("Welcome %{name}", i18n4v.Replace{"name":"John"})  // -> Welcome John

If translation is missing, it passes through translation keys as a translations. You can pass text for fall back:

_ := i18n4v.Translate

_("_short_key", "This is a long piece of text")  // -> This is a long piece of text

Context feature supports selecting translations from context (like gender). Of cource, you can use all features together that are described before:

MustAddFromString(`{
    "contexts": [
        {
            "matches": {"gender": "male"},
            "values": {
                "%{name} uploaded %n photos to their %{album} album": [
                      [0, 0, "%{name} uploaded %n photos to his %{album} album"],
                      [1, 1, "%{name} uploaded %n photo to his %{album} album"],
                      [2, null, "%{name} uploaded %n photos to his %{album} album"]
                ]
            }
        },
        {
            "matches": {"gender":"female"},
            "values": {
                "%{name} uploaded %n photos to their %{album} album": [
                      [0, 0, "%{name} uploaded %n photos to her %{album} album"],
                      [1, 1, "%{name} uploaded %n photo to her %{album} album"],
                      [2, null, "%{name} uploaded %n photos to her %{album} album"]
                ]
            }
        }
    ]
}`)

_ := i18n4v.Translate

_("%{name} uploaded %n photos to their %{album} album", 4,
    Replace{"name": "Jane", "album": "Hen's Night" },
    Context{"gender": "female" })
// -> Jane uploaded 4 photos to her Hen's Night album

This package is released under MIT license.

Index

• func Add(reader io.Reader, tag ...language.Tag) error
• func AddFromString(json string, tag ...language.Tag) error
• func AddWord(key, value string, tag ...language.Tag) error
• func MustAdd(reader io.Reader, tag ...language.Tag)
• func MustAddFromString(json string, tag ...language.Tag)
• func Reset()
• func Translate(key string, args ...interface{}) string
• type Context
• type Replace
• type Translator
  • func Create(reader io.Reader) (*Translator, error)
  • func CreateFromString(json string) (*Translator, error)
  • func MustCreate(reader io.Reader) *Translator
  • func MustCreateFromString(json string) *Translator
  • func SelectTranslator(lang string) *Translator
  • func SelectTranslatorWithRequest(r *http.Request) *Translator
  • func (t *Translator) AddWord(key, value string)
  • func (t *Translator) Translate(text string, args ...interface{}) string
• type TranslatorFunction
  • func Select(lang string) TranslatorFunction
  • func SelectWithRequest(r *http.Request) TranslatorFunction

Functions

func Add

func Add(reader io.Reader, tag ...language.Tag) error

Add registers dictionary to default Translator instance.

If JSON format is invalid, it returns error.

If tag is specified as 2nd parameter, it registers dictionary to specified language translator. You can access the registered translator with Select, SelectTranslator SelectTranslatorWithRequest, SelectWithRequest functions

func AddFromString

func AddFromString(json string, tag ...language.Tag) error

AddFromString registers dictionary to default Translator instance. It is similar to Add, but it accepts string instead of []byte.

If JSON format is invalid, it returns error.

If tag is specified as 2nd parameter, it registers dictionary to specified language translator. You can access the registered translator with Select, SelectTranslator SelectTranslatorWithRequest, SelectWithRequest functions

func AddWord

func AddWord(key, value string, tag ...language.Tag) error

AddWord adds key and value pair to existing dictionary. It is good for adding long text like email/html templates.

func MustAdd

func MustAdd(reader io.Reader, tag ...language.Tag)

MustAdd registers dictionary to default Translator instance.

If JSON format is invalid, it makes application panic. It is good for static initialization.

If tag is specified as 2nd parameter, it registers dictionary to specified language translator. You can access the registered translator with Select, SelectTranslator SelectTranslatorWithRequest, SelectWithRequest functions

func MustAddFromString

func MustAddFromString(json string, tag ...language.Tag)

MustAddFromString registers dictionary to default Translator instance. It is similar to MustAdd, but it accepts string instead of []byte.

If JSON format is invalid, it makes application panic. It is good for static initialization.

If tag is specified as 2nd parameter, it registers dictionary to specified language translator. You can access the registered translator with Select, SelectTranslator SelectTranslatorWithRequest, SelectWithRequest functions

func Reset

func Reset()

Reset clears default Translator instance.

func Translate

func Translate(key string, args ...interface{}) string

Translate function returns translated text.

It uses default Translator instance.

Types

type Context

type Context map[string]string

Context type is used for passing context parameters when translating.

type Replace

type Replace map[string]interface{}

Replace type is used for passing replacement parameters when translating.

type Translator

type Translator struct {
	// contains filtered or unexported fields
}

Translator type keeps translation dictionary and provides translation feature.

This instance is created via Create() functions. Or you can use default instance.

func Create

func Create(reader io.Reader) (*Translator, error)

Create returns new Translator instance.

If JSON format is invalid, it returns error.

func CreateFromString

func CreateFromString(json string) (*Translator, error)

CreateFromString returns new Translator instance. It is similar to Create, but it accepts string instead of []byte.

If JSON format is invalid, it returns error.

func MustCreate

func MustCreate(reader io.Reader) *Translator

MustCreate returns new Translator instance.

If JSON format is invalid, it makes application panic. It is good for static initialization.

func MustCreateFromString

func MustCreateFromString(json string) *Translator

MustCreateFromString returns new Translator instance. It is similar to MustCreate, but it accepts string instead of []byte.

If JSON format is invalid, it makes application panic. It is good for static initialization.

func SelectTranslator

func SelectTranslator(lang string) *Translator

SelectTranslator returns Translator instance from registered ones.

func SelectTranslatorWithRequest

func SelectTranslatorWithRequest(r *http.Request) *Translator

func (*Translator) AddWord

func (t *Translator) AddWord(key, value string)

func (*Translator) Translate

func (t *Translator) Translate(text string, args ...interface{}) string

Translate method returns translated text.

You can pass parameters like default text(string), count for pluralisation(int), replacement parameters(i18n4v.Replace), context parameters(i18n4v.Context). You can omit any parameters, but you should keep the order of them.

type TranslatorFunction

type TranslatorFunction func(text string, args ...interface{}) string

TranslatorFunction is a type of translation function

func Select

func Select(lang string) TranslatorFunction

func SelectWithRequest

func SelectWithRequest(r *http.Request) TranslatorFunction