@docpensieve/shared 0.5.0-beta.1 → 0.5.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docpensieve/shared",
-  "version": "0.5.0-beta.1",
+  "version": "0.5.0-beta.2",
   "description": "Utilities, constants and errors shared by the DocPensieve packages",
   "type": "module",
   "license": "MIT",

package/src/ui-strings.js

@@ -176,3 +176,45 @@ export function textDirection(lang) {
     return 'ltr';
   }
 }
+
+/**
+ * Whether a string names a language, as BCP 47 and CLDR understand it.
+ *
+ * The standard is BCP 47, and `Intl` carries it: a regex of our own refused
+ * `zh-Hans-CN`, which is valid, and accepted shapes that are not. Well formed
+ * is not the same as real, though — BCP 47 allows a language subtag of five
+ * to eight letters, so `francais` passes that check and would land in the
+ * markup as `lang="francais"`, a value no browser maps to a language. CLDR
+ * knows which tags name one; the subtag alone is asked, so that a region, a
+ * script or a private extension does not get in the way.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isLanguageCode(value) {
+  try {
+    Intl.getCanonicalLocales(value);
+    const names = new Intl.DisplayNames(['en'], { type: 'language', fallback: 'none' });
+    return names.of(new Intl.Locale(value).language) !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Name of a language, written in a language.
+ *
+ * @param {string} code Language code.
+ * @param {string} [inLang] Language the name is written in.
+ * @returns {string} The name, or the code itself when nothing names it.
+ */
+export function languageName(code, inLang = DEFAULT_LANGUAGE) {
+  try {
+    // The default fallback returns the code itself rather than nothing, so
+    // `?? code` only answers to the type: `of` is declared as possibly
+    // undefined, which it is only with `fallback: 'none'`.
+    return new Intl.DisplayNames([inLang], { type: 'language' }).of(code) ?? code;
+  } catch {
+    return code;
+  }
+}

package/types/ui-strings.d.ts

@@ -194,3 +194,26 @@ export declare function pageCount(count: number, strings: UiStrings, lang?: stri
  *   default, and what every page did before this existed.
  */
 export declare function textDirection(lang?: string): 'ltr' | 'rtl';
+/**
+ * Whether a string names a language, as BCP 47 and CLDR understand it.
+ *
+ * The standard is BCP 47, and `Intl` carries it: a regex of our own refused
+ * `zh-Hans-CN`, which is valid, and accepted shapes that are not. Well formed
+ * is not the same as real, though — BCP 47 allows a language subtag of five
+ * to eight letters, so `francais` passes that check and would land in the
+ * markup as `lang="francais"`, a value no browser maps to a language. CLDR
+ * knows which tags name one; the subtag alone is asked, so that a region, a
+ * script or a private extension does not get in the way.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export declare function isLanguageCode(value: string): boolean;
+/**
+ * Name of a language, written in a language.
+ *
+ * @param {string} code Language code.
+ * @param {string} [inLang] Language the name is written in.
+ * @returns {string} The name, or the code itself when nothing names it.
+ */
+export declare function languageName(code: string, inLang?: string): string;