# @matchlighter/nodal_i18n

> An fast I18n library with advanced interpolation and inheritance capabilities.

Latest version **0.2.0** (published 2022-07-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install @matchlighter/nodal_i18n
pnpm add @matchlighter/nodal_i18n
yarn add @matchlighter/nodal_i18n
bun add @matchlighter/nodal_i18n
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2022-07-08 |
| First published | 2019-09-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 230.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Matchlighter |
| Maintainers | matchlighter |

## Links

- npm: https://www.npmjs.com/package/@matchlighter/nodal_i18n
- Repository: git@git.matchlighter.net:matchlighter/js-micro-libs
- npm.io page: https://npm.io/package/@matchlighter/nodal_i18n

## Dependencies (1)

- [@matchlighter/common_library](https://npm.io/package/@matchlighter/common_library.md) ^1.0.0

## Recent versions

- 0.2.0 (latest) — 2022-07-08
- 0.1.3 — 2022-07-07
- 0.1.2 — 2022-07-07
- 0.1.1 — 2022-07-07
- 0.1.0 — 2019-09-11

## README

# @matchlighter/nodal_i18n

An fast I18n library with advanced interpolation and inheritance capabilities.

## Language Files
Language data is expressed as a plain Javascript object, and
can thus be transmitted to your frontend via JSON or can be imported from JSON or YAML files using tools such as Webpack.
Documentation of the language file format will primarily be written in YAML for its conciseness and better human-readability vs JSON.

Example Language file:
```yaml
title: Simple Application

base_tab:
  tooltip: $t(`${path[0:-1]}.title`)

header_tabs:
  home:
    title: Home
    # A basic entry that includes and interpolation. This example will resolve to "Return to "Simple Application" Home page"
    tooltip: Return to "$t(`title`)" Home page

  about:
    title: About Us

  # '.' separated object notation is also understood and interpreted the same as the above notation:
  pricing.title: Pricing

  # A `$base` key indicates an object that any other keys in the parent object (in this case `header_tabs`) should extend from.
  $base:
    # The overall effect of this example is that, for any tabs that do not contain a `tooltip` key, `header_tabs.$base.tooltip` will be returned.
    # In this example, however, `header_tabs.$base.tooltip` also implements an interpolation.
    # Thus `header_tabs.about.tooltip` is ultimately resolved to `header_tabs.about.title` or "About Us".
    tooltip: $t(`header_tabs.${path[1]}.title`)

  # The `$base` tag can also implement an interpolation, thus the following (given the definition of base_tab) would result in the same effect:
  $base: $t(`base_tab`)

  # This can also be achieved per-key using the `$extends` tag:
  contact:
    $extends: $t(`base_tab`)
    # ... Which may also be expressed as a list:
    $extends:
      - $t(`base_tab`)
    title: Contact Us

  # A `$missing` key can be provided and will be the default value if an _immediate_ subkey is missing.
  # Note that a present `$missing` will automatically inherit from `$base` as normal nodes do, but will only do so if `$missing` is actually specified.
  $missing:
    title: $path[-2]

  # To use `$base` for a non-present `$missing`, the following can be used:
  $missing: $base
```

### Interpolations

The interpolations syntax implements a small-but-powerful Domain-Specific-Language that can make your language files quite dynamic.
Values in the language file/data are interpreted as plain strings until a `$` character is encountered.

Examples:
- Simple Interpolation
  ```yaml
    # -- Language YAML:
    hello.planet: Hello $planet
  ```
  ```js
    // -- Queries:
    t('hello.planet', { planet: 'Earth' }) //-> "Hello Earth"
    t('hello.planet', { planet: 'Mars' }) //-> "Hello Mars"
  ```
- Lookup Interpolation
  ```yaml
    # -- Language YAML:
    planets:
      mars: Mars
      pluto: Pluto (Not Actually a Planet)
    hello:
      planet: Hello $t(`planets.$planet`)
  ```
  ```js
    // -- Queries:
    t('hello.planet', { planet: 'mars' }) //-> "Hello Mars"
    t('hello.planet', { planet: 'pluto' }) //-> "Hello Pluto (Not Actually a Planet)"
    ```

---
_Source: https://npm.io/package/@matchlighter/nodal_i18n · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._