Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@fluent/langneg

projectfluent57.5kApache-2.00.7.0TypeScript support: included

Language Negotiation API for Fluent

localization, l10n, internationalization, i18n, locale, language, language-negotiation

readme

@fluent/langneg

@fluent/langneg provides an API for negotiating languages. It's part of Project Fluent. Its main function is to provide functionality around the Intl.Locale API with a focus on language negotiation, matching and selection.

Installation

@fluent/langneg can be used both on the client-side and the server-side. You can install it from the npm registry or use it as a standalone script.

npm install @fluent/langneg

How to use

import { negotiateLanguages } from "@fluent/langneg";

const supportedLocales = negotiateLanguages(
  navigator.languages, // requested locales
  ["de", "en-US", "pl"], // available locales
  { defaultLocale: "en-US" }
);

The API reference is available at https://projectfluent.org/fluent.js/langneg.

Strategies

The API supports three negotiation strategies:

filtering (default)

In this strategy the algorithm will try to match as many available locales as possible for each of the requested locale.

Example:

requested: ['de-DE', 'fr-FR'] available: ['it', 'de', 'en-US', 'fr-CA', 'de-DE', 'fr', 'de-AU']

supported: ['de-DE', 'de', 'fr', 'fr-CA']

matching

In this strategy the algorithm will look for the best matching available locale for each requested locale.

Example:

requested: ['de-DE', 'fr-FR'] available: ['it', 'de', 'en-US', 'fr-CA', 'de-DE', 'fr', 'de-AU']

supported: ['de-DE', 'fr']

lookup

In this strategy the algorithm will try to find the single best locale for the requested locale list among the available locales.

Example:

requested: ['de-DE', 'fr-FR'] available: ['it', 'de', 'en-US', 'fr-CA', 'de-DE', 'fr', 'de-AU']

supported: ['de-DE']

API use:

let supported = negotiateLanguages(requested, available, {
  strategy: "matching",
});

Likely subtags

Fluent Language Negotiation module carries its own minimal list of likely subtags data, which is useful in finding most likely available locales in case the requested locale is too generic.

An example of that scenario is when the user requests en locale, and the application supports en-GB and en-US.

changelog

Changelog

0.7.0 (2023-03-13)

  • Drop Node.js v12 support, add v18 & latest to CI tests (#607)

0.6.2 (2022-05-03)

Bug Fixes

  • Adjust for updated linter rules (#590)

@fluent/langneg 0.6.1 (2021-12-21)

  • Add zh-mo and zh-tw to likely subtags (#570)
  • Add .js extension to imports (#581)

@fluent/langneg 0.6.0 (September 13, 2021)

  • Remove "type": "commonjs" from the package's root package.json, but add "type": "module" to the esm/ directory. (#556, #567)
  • Set Node.js 12 as the minimum supported version (#557)
  • Remove circular dependency (#545)

@fluent/langneg 0.5.2 (April 17, 2021)

  • Documentation fix. (#547)

@fluent/langneg 0.5.1 (April 9, 2021)

  • Better TypeScript annotations. (#525)

    Make array arguments read-only, and expose options type.

@fluent/langneg 0.5.0 (July 2, 2020)

  • Remove the compat.js build and compile everything to ES2018. (#472)

    TypeScript source code is now compiled to ES2018 files in the esm/ directory. These files are then bundled into a single index.js UMD file without any further transpilation.

    The compat.js build (available as @fluent/langneg/compat) was removed. Please use your own transpilation pipeline if ES2018 is too recent for your project.

    Refer to https://github.com/projectfluent/fluent.js/wiki/Compatibility for more information.

@fluent/langneg 0.4.0 (March 31, 2020)

  • Migrate @fluent/langneg to TypeScript. (#462)

    There are no functional nor API changes in this release.

@fluent/langneg 0.3.0 (July 25, 2019)

  • Rename fluent-langneg to @fluent/langneg.

fluent-langneg 0.3.0 (July 25, 2019)

  • Deprecate fluent-langneg in favor of @fluent/langneg.

fluent-langneg 0.2.0 (July 1, 2019)

  • Accept language variant tags as defined by UTS35. (#381)

fluent-langneg 0.1.1 (February 7, 2019)

  • Align the algorithm with C++/Rust implementations to fix the zh-HK scenario (#335)

  • Drop support for IE and old evergreen browsers. (#133)

    Currently supported are: Firefox 52+, Chrome 55+, Edge 15+, Safari 10.1+, iOS Safari 10.3+ and node 8.9+.

fluent-langneg 0.1.0 (August 17, 2017)

  • negotiateLanguages is now a named export.

    In code using fluent-langneg please change:

    import negotiateLanguages from 'fluent-langneg';

    to:

    import { negotiateLanguages } from 'fluent-langneg';

fluent-langneg 0.0.3

  • Added acceptedLanguages function for parsing the Accept-Language header.

  • Added * as a valid value for the requestedLocales argument.

  • The compat build is now transpiled using rollup-plugin-babel.

    This ensures that the "use strict" pragma is scoped to the UMD wrapper. It also correctly parses the top-level "this" keyword (which the previous setup turned into "undefined").

fluent-langneg 0.0.2

  • Added the "module" field to package.json for ES modules-compatible bundlers.

  • Updated the negotiation logic to match the C++ implementation.

fluent-langneg 0.0.1

  • Introduce Language Negotiation module for Fluent

    The initial release.