/i18n

simple yet effective (i hope) i18n for node.js

Primary LanguageTypeScript

@starkow/i18n

why?

  • i want to make it by my own
  • i didn't manage to find any good i18n packages
  • yeah

usage

locales/ru.json

{
  "foo": {
    "bar": [
      {
        "baz": "quix, {{hello}}"
      }
    ]
  },
  "declensions": {
    "apple": {
      "one": "яблоко",
      "few": "яблока",
      "many": "яблок",
      "other": "яблоки"
    }
  }
}

src/main.ts

import { resolve } from 'node:path'

import { I18n } from '@starkow/i18n'

const i18n = new I18n({
  localesPath: resolve(__dirname, 'locales'),
  currentLocale: 'ru',
  defaultLocale: 'en'
})

console.log(i18n.__('foo.bar.0.baz', { hello: 'world!' })) // "quix, world!" 

console.log(i18n.__n(1, 'declension.apple')) // "яблоко"
console.log(i18n.__n(3, 'declension.apple')) // "яблока"
console.log(i18n.__n(7, 'declension.apple')) // "яблок"

reference

new I18n(options), I18n.init(options), I18n.create(options)

options

All of these options are not required on initialization, however localesPath and currentLocale are required when getting a translation

key type description
localesPath string Path to locales
defaultLocale string Locale which will be used in case current locale was not found
fallbackLocale string Locale which will be used in case no translations found using currentLocale
currentLocale string Current locale
tags [string, string] Render templates tags
throwOnFailure boolean Should the package throw an error if it fails to find a translation?
parser Parser A function which is called when contents of a file are read
extensions string[] List of accepted file extensions (or an empty one if all files extensions are accepted)

locale

Returns current locale

Returns: string | undefined

i18n.locale

defaultLocale

Returns default locale - a locale which will be used in case current locale returns nothing

Returns: string | undefined

i18n.defaultLocale

fallbackLocale

Returns fallback locale - a locale which will be used when a translation using locale was not found

Returns: string | undefined

i18n.fallbackLocale

localesPath

Returns path to locales

Returns: string | undefined

i18n.localesPath

tags

Returns a list of render templates tags

Returns: [string, string]

i18n.tags = ['{', '}']

throwOnFailure

Returns whether the package will throw an error if it fails to find a translation

Returns: boolean

i18n.throwOnFailure = true

parser

Returns a function which is called when contents of a file are read

Returns: Parser ((contents: string) => Record<string, any>)

i18n.parser = YAML.parse

extensions

Returns a list of accepted file extensions (or an empty one if all files extensions are accepted)

Returns: string[]

i18n.extension = ['json']

getLanguages()

Returns all the languages found in localesPath

Returns: string[]

i18n.getLanguages()

exists(keys: MaybeArray<string>)

Returns whether [keys] exist in context of current locale

Returns: [keys] is array ? boolean[] : boolean

i18n.exists(['foo', 'bar'])

__r<T>(key: string)

Returns raw entity from the locale file

Returns: T

Aliases: r<T>(...), raw<T>(...)

i18n.__r<string[]>('menu.purchase.buttons')

__(keys: MaybeArray<string>, scope?: Scope)

Renders the template from the locale file

Returns: string

Aliases: t(...), translate(...)

i18n.__('hello.world')

Note: __ accepts string[] as the first argument which is a fallback list. @starkow/i18n iterates through this list and returns the first found translation. If it didn't find any, then returns the last key from the list

// { "bar": "quix" }
i18n.__(['foo', 'bar', 'baz']) // "quix"
// { "hello": "world" }
i18n.__(['foo', 'bar', 'baz']) // "baz"

__n(count: number, key: string, scope?: Scope)

Renders the plural template from the locale file

Returns: string

Aliases: p(...), plural(...)

i18n.__n(7, 'declension.book')

__l(key: string, scope?: Scope)

Returns a list of all of translations for a given key in each locale

Returns: string[]

Aliases: l(...), list(...)

i18n.__l('language_code')