Source: utils/localep.js

/**
 * @file This module provides utilities for handling locale-based translations.
 *
 * It includes functions to retrieve values from nested objects using dot notation keys
 * and to translate strings based on available locale files.
 *
 * @module    utils/localep
 * @requires  utils/type-utils
 * @requires  error
 * @requires  {@link https://www.npmjs.com/package/@mitsuki31/deepget npm:@mitsuki31/deepget}
 * @author    Ryuu Mitsuki <https://github.com/mitsuki31>
 * @since     2.0.0
 * @license   MIT
 */

'use strict';

const fs = require('node:fs');
const path = require('node:path');
const { DeepGet } = require('@mitsuki31/deepget');
const { getType } = require('../../lib/utils/type-utils');
const { InvalidTypeError } = require('../error');

/**
 * The system locale.
 * @type {string}
 * @since 2.0.0
 */
var SYSTEM_LOCALE = Intl.DateTimeFormat().resolvedOptions().locale.split('-')[0];

/**
 * The path to the locales directory.
 * @type {string}
 * @since 2.0.0
 */
var LOCALES_PATH = path.resolve(__dirname, '../../locales');
/**
 * The list of available locales.
 * @type {string[]}
 * @readonly
 * @since 2.0.0
 */
var AVAILABLE_LOCALES = Object.freeze(fs.readdirSync(LOCALES_PATH).map(p => {
  if (/.json$/.test(p)) return p.replace('.json', '');
}).filter(p => !!p));

/**
 * The locales object containing all locale data.
 * @type {Record<string, string | string[] | object>}
 * @readonly
 * @since 2.0.0
 */
var LOCALES = Object.freeze(AVAILABLE_LOCALES.reduce((acc, l) => {
  acc[l] = JSON.parse(fs.readFileSync(`${LOCALES_PATH}/${l}.json`));
  return acc;
}, {}));


/**
 * Retrieves a localized string for the given key based on the provided locale(s).
 *
 * This function attempts to fetch the translation string from the `LOCALES` object.
 * It follows a priority order where the first matching locale is used. If no match
 * is found, it falls back to system locale, default locale ('en'), or an empty string.
 *
 * ### Fallback Rules
 * - If the provided locale is not available, it falls back to the system locale.
 * - If the translation for the system locale is not available, it falls back to the English translation.
 *
 * ### Locale Priority
 * ```txt
 * User-defined Locale >> System Locale >> Default Locale (English)
 * ```
 *
 * @param {string} key - The key path to retrieve the translation.
 * @param {string | string[]} [locales] - The preferred locale(s) in order of priority.
 *                                        Can be a single string or an array of strings.
 *                                        Defaults to system locale if not specified.
 * @returns {string} The translated string if found, or the system default locale,
 *                   or the default English string, otherwise an empty string.
 *
 * @throws {InvalidTypeError} If `locales` is neither a string nor an array of strings.
 *
 * @example
 * ```json
 * // Assuming LOCALES contains:
 * {
 *   en: { greeting: "Hello" },
 *   fr: { greeting: "Bonjour" }
 * }
 * ```
 *
 * ```js
 * translate('greeting', 'fr'); // "Bonjour"
 * translate('greeting', ['es', 'fr']); // "Bonjour" (fallback to 'fr')
 * translate('greeting', 'ja'); // "Hello" (fallback to system locale, assuming 'en')
 * ```
 *
 * @package
 * @since   2.0.0
 */
function translate(key, locales) {
  if (typeof locales !== 'undefined'
      && (typeof locales !== 'string' && !Array.isArray(locales))) {
    throw new InvalidTypeError('Locale must be a string or an array of strings', {
      actualType: getType(locales),
      expectedType: "'string' | 'string[]'"
    });
  }
  locales = locales || SYSTEM_LOCALE;  // Default to system locale if not specified

  // Get the locale to be used
  let usedLocale;
  if (typeof locales === 'string') locales = [locales];
  for (const l of locales) {
    if (AVAILABLE_LOCALES.includes(l)) {
      usedLocale = l;
      break;
    }
  }
  // Push the default locale to the locales list for fallback on loop
  if (!locales.includes('en') || !usedLocale) locales.push('en');

  let value;
  for (let locale of locales) {
    locale = locale.split('-')[0];  // Remove the region part of the locale

    // Translate the key
    value = DeepGet(LOCALES[locale], key);
    if (typeof value !== 'undefined') break;
  }
  return value ? value : '';  // Return the value or an empty string if not found
}


module.exports = {
  translate
};