@fisharmy100/react-auto-i18n 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,637 @@
+import React$1 from 'react';
+
+/**
+ * The type of all language codes (i.e. the prefix of the {@link LangScriptCode})
+ */
+type LangCode = LangScriptCode extends `${infer L}_${string}` ? L : never;
+/**
+ * Gets the LangCode from the {@link LangScriptCode}. \
+ * **Example:**
+ * ```ts
+ * let langScript: LangScriptCode = "eng_Latn";
+ * console.log(getLangCode(langScript)); // prints out 'eng'
+ * ```
+ * @param code The {@link LangScriptCode}
+ * @returns the {@link LangCode} of the {@link LangScriptCode}
+ */
+declare function getLangCode(code: LangScriptCode): LangCode;
+/**
+ * Converts a raw string into a {@link LangCode}, with error checking
+ * @param str The string to be passed
+ * @returns A {@link LangCode} if the string is a valid {@link LangCode} or `null` if it is not
+ */
+declare function stringToLangCode(str: string): LangCode | null;
+/**
+ * Gets the english name of a {@link LangCode}
+ * @param code A {@link LangCode}
+ * @returns The english name of the passed {@link LangCode}
+ */
+declare function getEnglishLangName(code: LangCode): string | null;
+/**
+ * Gets the local name of a {@link LangCode}
+ * @param code A {@link LangCode}
+ * @returns The local name of the passed {@link LangCode}
+ */
+declare function getLocaleLangName(code: LangCode): string | null;
+
+/**
+ * The type of all script codes (i.e. the suffix of the {@link LangScriptCode})
+ */
+type ScriptCode = LangScriptCode extends `${string}_${infer S}` ? S : never;
+/**
+ * The direction that a given script is read, and should be rendered
+ * - `ltr`: Left-to-Right
+ * - `rtl`: Right-to-Left
+ */
+type ScriptDirection = "ltr" | "rtl";
+/**
+ * Gets the Script from the LangScriptCode. \
+ * **Example:**
+ * ```ts
+ * let langScript: LangScriptCode = "eng_Latn";
+ * console.log(getScriptCode(langScript)); // prints out 'Latn'
+ * ```
+ * @param code The {@link LangScriptCode}
+ * @returns the `Script` of the {@link LangScriptCode}
+ */
+declare function getScriptCode(code: LangScriptCode): ScriptCode;
+/**
+ * Converts a raw string into a {@link LangScriptCode}, with error checking
+ * @param str The string to be passed
+ * @returns A {@link LangScriptCode} if the string is a valid {@link LangScriptCode} or `null` if it is not
+ */
+declare function stringToLangScriptCode(str: string): LangScriptCode | null;
+/**
+ * Converts a raw string into a {@link ScriptCode}, with error checking
+ * @param str The string to be passed
+ * @returns A {@link ScriptCode} if the string is a valid {@link ScriptCode} or `null` if it is not
+ */
+declare function stringToScriptCode(str: string): ScriptCode | null;
+/**
+ * Gets the {@link ScriptDirection} from a {@link ScriptCode}
+ * @param script a {@link ScriptCode}
+ * @returns the {@link ScriptDirection} from the {@link ScriptCode}
+ */
+declare function getScriptDirection(script: ScriptCode): ScriptDirection;
+/**
+ * Gets the {@link ScriptDirection} from the {@link ScriptCode} of a {@link LangScriptCode}
+ * @param script a {@link LangScriptCode}
+ * @returns the {@link ScriptDirection} from the {@link ScriptCode} of a {@link LangScriptCode}
+ */
+declare function getLangScriptDirection(langScript: LangScriptCode): ScriptDirection;
+
+/**
+ * A country code
+ */
+type CountryCode = 'AE' | 'AF' | 'AL' | 'AM' | 'AO' | 'AR' | 'AT' | 'AW' | 'AU' | 'AZ' | 'BA' | 'BD' | 'BE' | 'BF' | 'BG' | 'BI' | 'BJ' | 'BN' | 'BO' | 'BR' | 'BT' | 'BW' | 'BY' | 'CA' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CL' | 'CN' | 'CM' | 'CO' | 'CR' | 'CV' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DZ' | 'EC' | 'EE' | 'EG' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FO' | 'FR' | 'GB' | 'GE' | 'GH' | 'GM' | 'GN' | 'GQ' | 'GR' | 'GT' | 'GW' | 'HK' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IN' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KR' | 'KZ' | 'LA' | 'LB' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'MA' | 'MD' | 'MG' | 'MK' | 'ML' | 'MM' | 'MN' | 'MR' | 'MT' | 'MU' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NE' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PG' | 'PH' | 'PK' | 'PL' | 'PT' | 'PY' | 'QA' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SI' | 'SK' | 'SL' | 'SN' | 'SO' | 'SR' | 'SS' | 'SY' | 'SZ' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TL' | 'TM' | 'TN' | 'TR' | 'TW' | 'TZ' | 'UA' | 'UG' | 'US' | 'UY' | 'UZ' | 'VE' | 'VN' | 'WS' | 'YE' | 'ZA' | 'ZM' | 'ZW';
+/**
+ * Gets the {@link CountryCode} for the given {@link LangCode}. Essentially, what country most primarily speaks this language.
+ * For example, this will return `US` even though Britain, Australia, etc. also speak the language.
+ * @param code The {@link LangCode}
+ * @returns A {@link CountryCode} which represents the country ***most commonly*** associated with that language. It will return null if there is no country typically associated with this language.
+ */
+declare function getCountryCode(code: LangCode): CountryCode | null;
+
+/**
+ * A helper wrapper object for the {@link LangScriptCode}, providing basic functions in an OOP style.
+ */
+declare class LangScriptObj {
+    /**
+     * The inner wrapped {@link LangScriptCode}
+     */
+    readonly code: LangScriptCode;
+    constructor(code: LangScriptCode);
+    /**
+     * A helper function for getting the {@link LangCode} for the wrapped {@link LangScriptCode}
+     * @returns The {@link LangCode} for the wrapped {@link LangScriptCode}
+     */
+    getLangCode(): LangCode;
+    /**
+     * A helper function for getting the {@link ScriptCode} for the wrapped {@link LangScriptCode}
+     * @returns The {@link ScriptCode} for the wrapped {@link LangScriptCode}
+     */
+    getScriptCode(): ScriptCode;
+    /**
+     * A helper function for getting the locale name for the wrapped {@link LangScriptCode}
+     * @returns The {@link LangCode} for the wrapped {@link LangScriptCode}
+     */
+    getName(): string | null;
+    /**
+     * A helper function for getting the english name for the wrapped {@link LangScriptCode}
+     * @returns The {@link LangCode} for the wrapped {@link LangScriptCode}
+     */
+    getEnglishName(): string | null;
+    /**
+     * A helper function for getting the {@link CountryCode} most associated with this {@link LangScriptCode}, or `null` if there is none
+     * @returns the {@link CountryCode} most associated with this `LangScriptCode, or `null` if there is none
+     */
+    getCountry(): CountryCode | null;
+    /**
+     * A helper function that invokes the {@link CountryFlag} component, with the country code most associated with this {@link LangScriptCode}, or null if there is none
+     * @returns the {@link CountryFlag} component, with the country code most associated with this {@link LangScriptCode}, or null if there is none
+     */
+    getCountryFlag(): React.ReactElement | null;
+    /**
+     * A helper function for getting the {@link ScriptDirection} for wrapped {@link LangScriptCode}
+     * @returns the {@link ScriptDirection} for wrapped {@link LangScriptCode}
+     */
+    getScriptDirection(): ScriptDirection;
+}
+
+/**
+ * Essentially represents all translations loaded for this application. It can be represented in JSON as:
+ * ```json
+ * {
+ *      "eng_Latn": {
+ *          "main.first": "...",
+ *          "main.second": "...",
+ *          ...
+ *      },
+ *      "fra_Latn": {
+ *          "main.first": "...",
+ *          "main.second": "...",
+ *          ...
+ *      },
+ *      "spa_Latn": {
+ *          "main.first": "...",
+ *          "main.second": "...",
+ *          ...
+ *      },
+ *      ...
+ * }
+ * ```
+ */
+type I18nDatabaseType = Partial<Readonly<Record<LangScriptCode, LanguageTranslations>>>;
+/**
+ * A map that contains translations for all keys for a given language.
+ */
+type LanguageTranslations = Partial<Readonly<Record<string, string | string[]>>>;
+/**
+ * The interface for a translation database
+ */
+interface I18nDatabase {
+    /**
+     * Gets the translation for a given language and key
+     * @param lang A {@link LangScriptCode}
+     * @param key A key for the given translation in the specified language
+     * @returns Either a single translation (for {@link __t}), multiple translations (for {@link __tv}), or `undefined` if there is no translations
+     */
+    get(lang: LangScriptCode, key: string): string[] | string | undefined;
+    /**
+     * @returns All the {@link LangScriptCode}'s that the database contains
+     */
+    langs(): LangScriptCode[];
+    /**
+     * Allows the user to add a listener to see if the internal state of the database has changed. This can be used for things like caching
+     * @param listener
+     */
+    addOnChangeListener(listener: () => void): void;
+    /**
+     * Allows the user to remove a listener that would fire if the internal state of the database has changed. This can be used for things like caching
+     * @param listener
+     */
+    removeOnChangeListener(listener: () => void): boolean;
+}
+/**
+ * A basic wrapper around the {@link I18nDatabaseType} which implements {@link I18nDatabase}. It also gives some helper functions for loading it from a file.
+ */
+declare class SimpleI18nDb implements I18nDatabase {
+    private readonly db;
+    constructor(db: I18nDatabaseType);
+    addOnChangeListener(): void;
+    removeOnChangeListener(): boolean;
+    /**
+     * Creates a {@link SimpleI18nDb} from a file. The file the path points to must be in the format of {@link I18nDatabaseType}
+     * @param path The path of the database file.
+     * @returns
+     */
+    static load(path: string): Promise<SimpleI18nDb>;
+    get(lang: LangScriptCode, key: string): string[] | string | undefined;
+    langs(): LangScriptCode[];
+}
+declare const FOLDER_LANGUAGE_MANIFEST_NAME: string;
+type FolderLanguageManifestType = {
+    langs: LangScriptCode[];
+};
+/**
+ * A cached database, which will only load languages if necessary.
+ */
+declare class CachedMultiFileI18nDb implements I18nDatabase {
+    private readonly supportedLangs;
+    private readonly db;
+    private readonly path;
+    private onChangedListeners;
+    /**
+     * @param path The folder path which contains all multiple files of type {@link LanguageTranslations} and each must be named using {@link LangScriptCode} followed by a `.json`
+     * @param langs Represents all of the languages that the translation folder contains. Essentially, if the folder has a file for a given language, add that language here.
+     */
+    constructor(path: string, langs: LangScriptCode[]);
+    /**
+     * Creates a {@link CachedMultiFileI18nDb} from a folder path.
+     * The folder path which contains all multiple files of type {@link LanguageTranslations}, and each must be named using {@link LangScriptCode} followed by a `.json`.
+     * It needs to point to a folder inside of the `public` folder, and the folder must contain a `manifest.json` file of the format {@link FolderLanguageManifestType}
+     */
+    static load(folder: string): Promise<CachedMultiFileI18nDb>;
+    get(lang: LangScriptCode, key: string): string[] | string | undefined;
+    langs(): LangScriptCode[];
+    addOnChangeListener(listener: () => void): void;
+    removeOnChangeListener(listener: () => void): boolean;
+    private invokeOnChangeListeners;
+}
+/**
+ * The default (empty) {@link I18nDatabase}.
+ */
+declare const I18nDatabaseDefault: I18nDatabase;
+
+/**
+ * A list of all LangScriptCodes supported by the translation engine
+ */
+declare const LANG_SCRIPT_CODES: readonly ["ace_Arab", "ace_Latn", "acm_Arab", "acq_Arab", "aeb_Arab", "afr_Latn", "als_Latn", "amh_Ethi", "apc_Arab", "arb_Arab", "arb_Latn", "arg_Latn", "ars_Arab", "ary_Arab", "arz_Arab", "asm_Beng", "ast_Latn", "awa_Deva", "ayr_Latn", "azb_Arab", "azj_Latn", "bak_Cyrl", "bam_Latn", "ban_Latn", "bel_Cyrl", "bem_Latn", "ben_Beng", "bho_Deva", "bjn_Arab", "bjn_Latn", "bod_Tibt", "bos_Latn", "brx_Deva", "bug_Latn", "bul_Cyrl", "cat_Latn", "ceb_Latn", "ces_Latn", "chv_Cyrl", "cjk_Latn", "ckb_Arab", "cmn_Hans", "cmn_Hant", "crh_Latn", "cym_Latn", "dan_Latn", "dar_Cyrl", "deu_Latn", "dgo_Deva", "dik_Latn", "dyu_Latn", "dzo_Tibt", "ekk_Latn", "ell_Grek", "eng_Latn", "epo_Latn", "eus_Latn", "ewe_Latn", "fao_Latn", "fij_Latn", "fil_Latn", "fin_Latn", "fon_Latn", "fra_Latn", "fur_Latn", "fuv_Latn", "gaz_Latn", "gla_Latn", "gle_Latn", "glg_Latn", "gom_Deva", "gug_Latn", "guj_Gujr", "hat_Latn", "hau_Latn", "heb_Hebr", "hin_Deva", "hne_Deva", "hrv_Latn", "hun_Latn", "hye_Armn", "ibo_Latn", "ilo_Latn", "ind_Latn", "isl_Latn", "ita_Latn", "jav_Latn", "jpn_Jpan", "kaa_Latn", "kab_Latn", "kac_Latn", "kam_Latn", "kan_Knda", "kas_Arab", "kas_Deva", "kat_Geor", "kaz_Cyrl", "kbp_Latn", "kea_Latn", "khk_Cyrl", "khm_Khmr", "kik_Latn", "kin_Latn", "kir_Cyrl", "kmb_Latn", "kmr_Latn", "knc_Arab", "knc_Latn", "kor_Hang", "ktu_Latn", "lao_Laoo", "lij_Latn", "lim_Latn", "lin_Latn", "lit_Latn", "lld_Latn", "lmo_Latn", "ltg_Latn", "ltz_Latn", "lua_Latn", "lug_Latn", "luo_Latn", "lus_Latn", "lvs_Latn", "mag_Deva", "mai_Deva", "mal_Mlym", "mar_Deva", "mfe_Latn", "mhr_Cyrl", "min_Arab", "min_Latn", "mkd_Cyrl", "mlt_Latn", "mni_Beng", "mni_Mtei", "mos_Latn", "mri_Latn", "mya_Mymr", "myv_Cyrl", "nld_Latn", "nno_Latn", "nob_Latn", "npi_Deva", "nqo_Nkoo", "nso_Latn", "nus_Latn", "nya_Latn", "oci_Latn", "ory_Orya", "pag_Latn", "pan_Guru", "pap_Latn", "pbt_Arab", "pes_Arab", "plt_Latn", "pol_Latn", "por_Latn", "prs_Arab", "quy_Latn", "ron_Latn", "run_Latn", "rus_Cyrl", "sag_Latn", "san_Deva", "sat_Olck", "scn_Latn", "shn_Mymr", "sin_Sinh", "slk_Latn", "slv_Latn", "smo_Latn", "sna_Latn", "snd_Arab", "snd_Deva", "som_Latn", "sot_Latn", "spa_Latn", "srd_Latn", "srp_Cyrl", "ssw_Latn", "sun_Latn", "swe_Latn", "swh_Latn", "szl_Latn", "tam_Taml", "taq_Latn", "taq_Tfng", "tat_Cyrl", "tel_Telu", "tgk_Cyrl", "tha_Thai", "tir_Ethi", "tpi_Latn", "tsn_Latn", "tso_Latn", "tuk_Latn", "tum_Latn", "tur_Latn", "twi_Latn", "tyv_Cyrl", "uig_Arab", "ukr_Cyrl", "umb_Latn", "urd_Arab", "uzn_Latn", "uzs_Arab", "vec_Latn", "vie_Latn", "vmw_Latn", "war_Latn", "wol_Latn", "wuu_Hans", "xho_Latn", "ydd_Hebr", "yor_Latn", "yue_Hant", "zgh_Tfng", "zsm_Latn", "zul_Latn"];
+/**
+ * The type of all supported {@link LangScriptCode}'s
+ */
+type LangScriptCode = typeof LANG_SCRIPT_CODES[number];
+/**
+ * A list of all {@link LangCode}'s
+ */
+declare const LANG_CODES: LangCode[];
+/**
+ * A list of all {@link ScriptCode}'s
+ */
+declare const SCRIPT_CODES: ScriptCode[];
+/**
+ * A utility function for converting a {@link LangCode} and a {@link LangCode} into a {@link LangScriptCode}
+ * @param lang The {@link LangCode} for the {@link LangScriptCode}
+ * @param script The {@link LangCode} for the {@link LangScriptCode}
+ * @returns The formatted {@link LangScriptCode}
+ */
+declare function formatLangScriptCode(lang: LangCode, script: ScriptCode): LangScriptCode;
+
+/**
+ * The properties for {@link CountryFlag}
+ */
+type CountryFlagProps = React$1.HtmlHTMLAttributes<HTMLSpanElement> & {
+    /**
+     * The {@link CountryCode} for {@link CountryFlag}
+     */
+    country: CountryCode;
+};
+/**
+ * Renders a country flag icon based on the provided country code.
+ * @param props - The component props
+ * @param props.country - The country code (e.g., 'US', 'FR', 'DE'), see all values in {@link CountryCode}
+ * @param props.className - Optional additional CSS class names to apply to the flag element
+ * @param props.rest - Additional HTML span element attributes
+ * @returns A React element displaying the country flag icon
+ */
+declare function CountryFlag({ country, className, ...rest }: CountryFlagProps): React$1.ReactElement;
+
+/**
+ * The properties for the {@link I18nFileProvider}
+ */
+type I18nFileProviderProps = {
+    /**
+     * The file path to the json database. It needs to point to a file inside of the `public` folder and the json must be in the format of {@link I18nDatabaseType}.
+     */
+    path: string;
+    /**
+     * The children of this component
+     */
+    children: React$1.ReactNode;
+    /**
+     * The default language for the provider. Defaults to `"eng_Latn"`
+     */
+    defaultLang: LangScriptCode;
+};
+/**
+ * A wrapper around the {@link I18nProvider} and {@link SimpleI18nDb}, which loads in a static translation json database file from the `public` folder.
+ * @param props The {@link I18nFileProviderProps} for this provider.
+ *
+ * ### **Example**
+ * ```tsx
+ * import { StrictMode } from 'react'
+ * import { createRoot } from 'react-dom/client'
+ * import App from './App.tsx'
+ * import { I18nProvider, RawI18nDb } from "react-auto-i18n";
+ *
+ * createRoot(document.getElementById('root')!).render(
+ * 	  <I18nFileProvider
+ * 	  	defaultLang="eng_Latn"
+ * 	  	path="./translations.json"
+ * 	  >
+ * 	  	<App />
+ * 	  </I18nFileProvider>
+ * )
+ * ```
+ */
+declare function I18nFileProvider({ path, children, defaultLang, }: I18nFileProviderProps): React$1.ReactElement;
+
+/**
+ * The context type for the {@link I18nProvider}
+ */
+interface I18nContextType {
+    /**
+     * The currently set {@link LangScriptCode}
+     */
+    readonly locale: LangScriptCode;
+    /**
+     * Gets a wrapper {@link LangScriptObj} around this locale
+     * @returns a wrapper {@link LangScriptObj} around this locale
+     */
+    readonly getLocaleObj: () => LangScriptObj;
+    /**
+     * The currently set {@link I18nDatabase}
+     */
+    readonly database: I18nDatabase;
+    /**
+     * Sets the current {@link LangScriptCode}
+     * @param locale The current local to set
+     */
+    readonly setLocale: (locale: LangScriptCode) => void;
+    /**
+     * Sets the current {@link I18nDatabase}
+     * @param locale The current local to set
+     */
+    readonly setDatabase: (database: I18nDatabase) => void;
+    /**
+     * This is essentially a helper function for doing `.database.langs()`
+     * @returns Returns all the loaded {@link LangScriptCode}'s in the current I18nDatabase.
+     */
+    readonly getLocales: () => LangScriptCode[];
+}
+/**
+ * The properties for the {@link I18nProvider}
+ */
+type I18nProviderProps = {
+    /**
+     * The providers children
+     */
+    children: React$1.ReactNode;
+    /**
+     * The default language code. When passed to the {@link I18nProvider}, defaults to `"eng_Latn"`
+     */
+    defaultLang: LangScriptCode;
+    /**
+     * The {@link I18nDatabase} for this provider
+     */
+    db: I18nDatabase;
+};
+/**
+ * The provider for the {@link I18nDatabase} and current local.
+ *
+ * Allows for getting and setting the global state used by {@link __t} in a more React like way.
+ *
+ * ### **Example:**
+ * ```tsx
+ * import { StrictMode } from 'react'
+ * import { createRoot } from 'react-dom/client'
+ * import App from './App.tsx'
+ * import { I18nProvider, RawI18nDb } from "react-auto-i18n";
+ * import translations from "./assets/translations.json";
+ *
+ * const db = new RawI18nDb(translations);
+ *
+ * createRoot(document.getElementById('root')!).render(
+ * 	  <I18nProvider
+ * 	  	defaultLang="eng_Latn"
+ * 	  	db={db}
+ * 	  >
+ * 	  	<App />
+ * 	  </I18nProvider>
+ * )
+ * ```
+ *
+ * @param props The {@link I18nProviderProps} for this provider
+ */
+declare function I18nProvider({ children, defaultLang, db: dbInit, }: I18nProviderProps): React$1.ReactElement;
+/**
+ * Allows for the modification and usage of the global database and locale states. Must be used on the context of a {@link I18nProvider}.
+ *
+ * ### **Example:**
+ * ```ts
+ * const i18n = useI18n();
+ * i18n.setLocale("spa_Latn");
+ *
+ * let msg = __t("message", "Hello!");
+ * console.log(msg); // Hola!
+ * ```
+ * @returns The instance of the current {@link I18nProvider}
+ */
+declare function useI18n(): I18nContextType;
+
+/**
+ * The properties for the {@link I18nMultiFileProvider}
+ */
+type I18nMultiFileProviderProps = {
+    /**
+     * The folder path which contains all multiple files of type {@link LanguageTranslations}, and each must be named using {@link LangScriptCode} followed by a `.json`.
+     * It needs to point to a folder inside of the `public` folder, and the folder must contain a `manifest.json` file of the format {@link FolderLanguageManifestType}
+     */
+    path: string;
+    /**
+     * The children of this component
+     */
+    children: React$1.ReactNode;
+    /**
+     * The default language for the provider. Defaults to `"eng_Latn"`
+     */
+    defaultLang: LangScriptCode;
+};
+/**
+ * A wrapper around the {@link I18nProvider} and {@link CachedMultiFileI18nDb}, which loads in a static translation json database folder from the `public` folder.
+ * @param props The {@link I18nMultiFileProviderProps} for this provider.
+ *
+ * ### **Example**
+ * ```tsx
+ * import { StrictMode } from 'react'
+ * import { createRoot } from 'react-dom/client'
+ * import App from './App.tsx'
+ * import { I18nProvider, RawI18nDb } from "react-auto-i18n";
+ *
+ * createRoot(document.getElementById('root')!).render(
+ * 	  <I18nMultiFileProvider
+ * 	  	defaultLang="eng_Latn"
+ * 	  	path="./translations"
+ * 	  >
+ * 	  	<App />
+ * 	  </I18nMultiFileProvider>
+ * )
+ * ```
+ *
+ */
+declare function I18nMultiFileProvider({ path, children, defaultLang, }: I18nMultiFileProviderProps): React$1.ReactElement;
+
+/**
+ * Sets the raw database used for translation. This is used by the {@link __t} and {@link __tv} functions. \
+ * **NOTE:** Prefer to use `useI18n().setDatabase(...)`, as this updates the current state.
+ * @param db
+ */
+declare function setI18nDatabaseRaw(db: I18nDatabase): void;
+/**
+ * Gets the raw database used for translation, which used by the {@link __t} and {@link __tv} functions. \
+ * **NOTE:** Prefer to use `useI18n().database` hook
+ * @returns the raw `I18nDatabase` database
+ */
+declare function getI18nDatabaseRaw(): I18nDatabase;
+/**
+ * Sets the raw locale used for translation. This is used by the {@link __t} and {@link __tv} functions. \
+ * **NOTE:** Prefer to use `useI18n().setLocale(...)`, as this updates the current state.
+ * @param locale
+ */
+declare function setCurrentLocalRaw(locale: LangScriptCode): void;
+/**
+ * Gets the raw current locale used for translation, which used by the {@link __t} and {@link __tv} functions. \
+ * **NOTE:** Prefer to use `useI18n().locale` hook
+ * @returns The current raw `LangScriptCode` locale
+ */
+declare function getCurrentLocalRaw(): LangScriptCode;
+/**
+ * The primary translation function for this API.
+ * When using {@link https://github.com/FishArmy100/react-auto-i18n/tree/main/packages/auto-i18n-cli auto-i18n-cli} to parse the program and generate the database automatically, both arguments must be raw string literals.
+ * The {@link https://github.com/FishArmy100/react-auto-i18n/tree/main/packages/auto-i18n-cli auto-i18n-cli} looks for all invocations of this function and generates a `I18nDatabase` compatible json file, with the proper translations.
+ *
+ * ### **Translation (using auto-i18n-cli):**
+ * ```ts
+ * // file.ts
+ * let msg = __t("message", "Hello!");
+ * ```
+ * Translation command:
+ * `npx auto-i18n-cli -i "./file.ts" -o "./translations.json" -l spa_Latn -s eng_Latn -b azure --azureKey "..."`
+ *
+ * Outputs:
+ * ```json
+ * {
+ *     "eng_Latn": {
+ *         "message": "Hello!"
+ *     },
+ *     "spa_Latn": {
+ *         "message": "Hola!"
+ *     }
+ * }
+ * ```
+ *
+ * ### **Usage**
+ * ```ts
+ * import db from "./translations.json";
+ * setI18nDatabaseRaw(db);
+ * setCurrentLocalRaw("spa_Latn");
+ * let msg = __t("message", "Hello!");
+ *
+ * console.log(msg); // Hola!
+ * ```
+ *
+ * ### **Escape Code**
+ * You can use double curly braces `{{...}}` to stop the translation engine from translating any text inside. The curly braces are removed after translation.
+ * If a `$` is placed before the text inside of the escape code, it is treated as a variable which values can be passed,
+ * and incorporated into the text.
+ *
+ * **NOTE:** the passed arguments are **NOT** translated
+ * ```ts
+ * import db from "./translations.json";
+ * setI18nDatabaseRaw(db);
+ * setCurrentLocalRaw("spa_Latn");
+ *
+ * let msg = __t("message", "Hello there! this is a test message for the {{'react-auto-i18n'}} program.");
+ *
+ * assert(msg === "Hola, este es un mensaje de prueba para el programa 'react-auto-i18n'.")
+ * ```
+ *
+ * @param key The key for the translation
+ * @param message The message to be translated
+ * @param arg A object that is passed as the argument to the selection functions and used for variable substitution
+ * @returns The translation of the message for the currently set locale.
+ */
+declare function __t<T extends {
+    [k: string]: any | undefined;
+}>(key: string, message: string, arg?: T): string;
+type TVArgs<T> = [...[string, (t: T) => boolean][], string];
+/**
+ * The secondary translation function for this API.
+ * When using {@link https://github.com/FishArmy100/react-auto-i18n/tree/main/packages/auto-i18n-cli auto-i18n-cli} to parse the program and generate the database automatically, `key` must be a string literal and `messages`
+ * must be an array literal, with the last argument being a string literal and all previous elements being an array literal with
+ * a string literal as the first element.
+ *
+ * The {@link https://github.com/FishArmy100/react-auto-i18n/tree/main/packages/auto-i18n-cli auto-i18n-cli} looks for all invocations of this function and generates a `I18nDatabase` compatible json file, with the proper translations.
+ *
+ * ### **Translation (using auto-i18n-cli):**
+ * ```ts
+ * // file.ts
+ * const msg = __tv("test.message.v", [
+ *	  ["You have one apple", ({count}) => count == 1],
+ *	  ["You have {{$count}} apples", ({count}) => count > 1],
+ *	  "You have no apples"
+ * ], { count: appleCount })
+ * ```
+ * Translation command:
+ * `npx auto-i18n-cli -i "./file.ts" -o "./translations.json" -l spa_Latn -s eng_Latn -b azure --azureKey "..."`
+ *
+ * Outputs:
+ * ```json
+ * {
+ *     "eng_Latn": {
+ *         "test.message.v": [
+ *             "You have one apple",
+ *             "You have {{$count}} apples",
+ *             "You have no apples"
+ *         ]
+ *     },
+ *     "spa_Latn": {
+ *          "test.message.v": [
+ *             "Tienes una manzana",
+ *             "Tienes {{$count}} manzanas",
+ *             "No tienes manzanas"
+ *         ]
+ *     }
+ * }
+ * ```
+ *
+ * ### **Usage**
+ * ```ts
+ * import db from "./translations.json";
+ * setI18nDatabaseRaw(db);
+ * setCurrentLocalRaw("spa_Latn");
+ *
+ * const appleCount = 5;
+ *
+ * const msg = __tv("test.message.v", [
+ *	  ["You have one apple", ({count}) => count == 1],
+ *	  ["You have {{$count}} apples", ({count}) => count > 1],
+ *	  "You have no apples"
+ * ], { count: appleCount })
+ *
+ * console.log(msg); // Tienes 5 manzanas!
+ * ```
+ *
+ * ### **Escape Code**
+ * You can use double curly braces `{{...}}` to stop the translation engine from translating any text inside.
+ * The curly braces are removed after translation.
+ * If a `$` is placed before the text inside of the escape code, it is treated as a variable which values can be passed,
+ * and incorporated into the text.
+ *
+ * **NOTE:** the passed arguments are **NOT** translated
+ * ```ts
+ * import db from "./translations.json";
+ * setI18nDatabaseRaw(db);
+ * setCurrentLocalRaw("spa_Latn");
+ *
+ * const appleCount = 5;
+ *
+ * const msg = __tv("test.message.v", [
+ *	  ["You have one apple", ({count}) => count == 1],
+ *	  ["You have {{$count}} apples", ({count}) => count > 1],
+ *	  "You have no apples"
+ * ], { count: appleCount })
+ *
+ * console.log(msg); // Tienes 5 manzanas!
+ * ```
+ *
+ * @param key The key for the translation
+ * @param messages An array of message variants
+ * @param arg A object that is passed as the argument to the selection functions and used for variable substitution
+ * @returns The translation of the message for the currently set locale.
+ */
+declare function __tv<T extends {
+    [k: string]: any | undefined;
+}>(key: string, messages: TVArgs<T>, arg: T): string;
+
+export { CachedMultiFileI18nDb, type CountryCode, CountryFlag, type CountryFlagProps, FOLDER_LANGUAGE_MANIFEST_NAME, type FolderLanguageManifestType, type I18nContextType, type I18nDatabase, I18nDatabaseDefault, type I18nDatabaseType, I18nFileProvider, type I18nFileProviderProps, I18nMultiFileProvider, type I18nMultiFileProviderProps, I18nProvider, type I18nProviderProps, LANG_CODES, LANG_SCRIPT_CODES, type LangCode, type LangScriptCode, LangScriptObj, type LanguageTranslations, SCRIPT_CODES, type ScriptCode, type ScriptDirection, SimpleI18nDb, type TVArgs, __t, __tv, __t as default, formatLangScriptCode, getCountryCode, getCurrentLocalRaw, getEnglishLangName, getI18nDatabaseRaw, getLangCode, getLangScriptDirection, getLocaleLangName, getScriptCode, getScriptDirection, setCurrentLocalRaw, setI18nDatabaseRaw, stringToLangCode, stringToLangScriptCode, stringToScriptCode, useI18n };