https://github.com/pcdevil/eleventy-plugin-intl-utils
https://github.com/pcdevil/eleventy-plugin-intl-utils
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/pcdevil/eleventy-plugin-intl-utils
- Owner: pcdevil
- License: mit
- Created: 2021-12-12T19:57:47.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-03-23T09:07:41.000Z (almost 3 years ago)
- Last Synced: 2025-03-04T16:41:44.759Z (about 1 year ago)
- Language: JavaScript
- Size: 194 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# eleventy-plugin-intl-utils
A set of internationalization utils for [Eleventy](https://www.11ty.dev/).
## Motivation
It's super fast to create a static website with **Eleventy** and with the help of [`eleventy-plugin-i18n`](https://www.npmjs.com/package/eleventy-plugin-i18n) localization can be done with ease too.
However it only gives solution for static data and dynamic data still needs treatment during layout rendering. This plugin aims to help with a set of [filters](https://www.11ty.dev/docs/filters/) and [shortcodes](https://www.11ty.dev/docs/shortcodes/).
The implementations of the filters are mostly wrappers around the [ECMAScript Internationalization API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) with a little _bit of sugar_.
## Usage
This guide corresponds to [Eleventy documentation](https://www.11ty.dev/docs/plugins/#add-the-plugin-to-eleventy-in-your-config-file):
1. Install the package
```bash
npm install --save @pcdevil/eleventy-plugin-intl-utils
```
2. Add to your config file
```javascript
// file: .eleventy.js
const intlUtils = require('@pcdevil/eleventy-plugin-intl-utils');
module.exports = function (eleventyConfig) {
// ...
const intlUtilConfig = {
locale: 'en-GB',
};
eleventyConfig.addPlugin(intlUtils, intlUtilConfig);
};
```
## Configuration object
A general configuration object can be passed optionally via Eleventy config when the plugin is initiated. This sections lists the available configuration properties.
### `locale`
This property affects the output language of the filters. See [`locales` argument section on Intl page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument) for more info.
- **Type**: String
- **Default value**: `undefined` (**Node.js** will pick up the system's language)
- **Example values**: `"en-GB"`, `"hu"`
## Filters
### `country_name`
Transforms a country code into a country name. Useful to display author's location.
- **Used Internationalization API**: `Intl.DisplayNames()` with _region_ type ([MDN article](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames/DisplayNames))
#### LiquidJS Example
```
{% assign country = "FR" %}
{{ country | country_name }}
```
This renders "France" when the `intlUtilConfig.locale` is `en`.
### `language_name`
Transforms a language code to a renderable text. Useful for language selectors or when the current language is displayed.
- **Used Internationalization API**: `Intl.DisplayNames()` with _language_ type ([MDN article](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames/DisplayNames#using_type_language_with_languagedisplay))
#### LiquidJS Example
```
{% assign language = "en-GB" %}
{{ language | language_name }}
```
This renders "British English" when the `intlUtilConfig.locale` is `en`.
### `short_datetime_format`
Transforms a date string to a short date time text. Useful for blog post dates.
- **Used Internationalization API**: `Intl.DateTimeFormat()` with _short_ date and time style ([MDN article](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat))
#### LiquidJS Example
```
{% assign postDate = "2021-12-12 17:36 +0100" %}
{{ postDate | short_datetime_format }}
```
This renders "12/12/21, 5:36 PM" when the `intlUtilConfig.locale` is `en`.
## Shortcodes
### `year_interval`
Transforms two date strings to a year range. Useful when a larger time interval is presented.
The input should be an array with two date string and the first one should precede before the second one.
- **Used Internationalization API**: `Intl.DateTimeFormat.prototype.formatRange()` with _numeric_ year ([MDN article](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatRange))
#### LiquidJS Example
```
{% assign startDate = "2011-05-16 11:00 +0200" %}
{% assign endDate = "2020-03-01 00:00 +0100" %}
{% year_interval startDate, endDate %}
```
This renders "2011 – 2020" (with en dash in the middle) when the `intlUtilConfig.locale` is `en`.
#### Fallback value
The second `endDate` argument can be omitted and it has the current date as default value.
This behaviour helps when an open-ended / ongoing interval needs be displayed:
```
{% assign startDate = "2011-05-16 11:00 +0200" %}
{% year_interval startDate %}
```
This renders "2011 – 2021" (with en dash in the middle) when the `intlUtilConfig.locale` is `en` and the current year is 2021.
### `year_open_interval`
Transforms a date string into an _open_ year range where the end date is absent. Useful when a ongoing interval is presented.
- **Used Internationalization API**: `Intl.DateTimeFormat.prototype.formatRange()` with _numeric_ year ([MDN article](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatRange))
#### LiquidJS Example
```
{% assign startDate = "2011-05-16 11:00 +0200" %}
{% year_interval startDate %}
```
This renders "2011 – " (with en dash in the middle) when the `intlUtilConfig.locale` is `en`.
#### Difference from `year_interval`
While the [`year_interval`](#year_interval) shortcode always created a _closed_ year range (by applying the current year as default), the `year_open_interval` only displays the start date.
## License
Available under the [MIT license](LICENSE.md).