eleventy-plugin-intl-utils

A set of internationalization utils for Eleventy.

Motivation

It's super fast to create a static website with Eleventy and with the help of 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 and shortcodes.

The implementations of the filters are mostly wrappers around the ECMAScript Internationalization API with a little bit of sugar.

Usage

This guide corresponds to Eleventy documentation:

1. Install the package

   npm install --save @pcdevil/eleventy-plugin-intl-utils

2. Add to your config file

   // 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 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)

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)

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)

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)

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)

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 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.