Manuel Cillero
896b066ca9
- Incluye recursos Fluent básicos y pruebas asociadas. - Nueva variable de configuración global para definir el idioma predeterminado.
364 lines
12 KiB
Rust
364 lines
12 KiB
Rust
//! Localización (L10n).
|
|
//!
|
|
//! `PageTop` utiliza las especificaciones de [Fluent](https://www.projectfluent.org/) para la
|
|
//! localización de aplicaciones, y aprovecha [fluent-templates](https://docs.rs/fluent-templates/)
|
|
//! para integrar los recursos de traducción directamente en el binario de la aplicación.
|
|
//!
|
|
//! # Sintaxis Fluent (FTL)
|
|
//!
|
|
//! El formato empleado para describir los recursos de traducción se denomina
|
|
//! [FTL](https://www.projectfluent.org/fluent/guide/). Está diseñado para ser legible y expresivo,
|
|
//! permitiendo representar construcciones complejas del lenguaje natural como el género, el plural
|
|
//! o las conjugaciones verbales.
|
|
//!
|
|
//! # Recursos Fluent
|
|
//!
|
|
//! Por defecto, las traducciones se organizan en el directorio *src/locale*, con subdirectorios
|
|
//! para cada [Identificador de Idioma Unicode](https://docs.rs/unic-langid/) válido. Podríamos
|
|
//! tener una estructura como esta:
|
|
//!
|
|
//! ```text
|
|
//! src/locale/
|
|
//! ├── common.ftl
|
|
//! ├── en-US/
|
|
//! │ ├── default.ftl
|
|
//! │ └── main.ftl
|
|
//! ├── es-ES/
|
|
//! │ ├── default.ftl
|
|
//! │ └── main.ftl
|
|
//! ├── es-MX/
|
|
//! │ ├── default.ftl
|
|
//! │ └── main.ftl
|
|
//! └── fr/
|
|
//! ├── default.ftl
|
|
//! └── main.ftl
|
|
//! ```
|
|
//!
|
|
//! Ejemplo de un archivo *src/locale/en-US/main.ftl*:
|
|
//!
|
|
//! ```text
|
|
//! hello-world = Hello world!
|
|
//! hello-user = Hello, {$userName}!
|
|
//! shared-photos =
|
|
//! {$userName} {$photoCount ->
|
|
//! [one] added a new photo
|
|
//! *[other] added {$photoCount} new photos
|
|
//! } of {$userGender ->
|
|
//! [male] him and his family
|
|
//! [female] her and her family
|
|
//! *[other] the family
|
|
//! }.
|
|
//! ```
|
|
//!
|
|
//! Y su archivo equivalente para español *src/locale/es-ES/main.ftl*:
|
|
//!
|
|
//! ```text
|
|
//! hello-world = Hola mundo!
|
|
//! hello-user = ¡Hola, {$userName}!
|
|
//! shared-photos =
|
|
//! {$userName} {$photoCount ->
|
|
//! [one] ha añadido una nueva foto
|
|
//! *[other] ha añadido {$photoCount} nuevas fotos
|
|
//! } de {$userGender ->
|
|
//! [male] él y su familia
|
|
//! [female] ella y su familia
|
|
//! *[other] la familia
|
|
//! }.
|
|
//! ```
|
|
//!
|
|
//!
|
|
//! # Cómo aplicar la localización en tu código
|
|
//!
|
|
//! Una vez creado el directorio con los recursos FTL, basta con utilizar la macro
|
|
//! [`include_locales!`](crate::include_locales) para integrarlos en la aplicación.
|
|
//!
|
|
//! Si los recursos se encuentran en el directorio `"src/locale"`, sólo hay que declarar:
|
|
//!
|
|
//! ```rust
|
|
//! use pagetop::prelude::*;
|
|
//!
|
|
//! include_locales!(LOCALES_SAMPLE);
|
|
//! ```
|
|
//!
|
|
//! Pero si están ubicados en otro directorio, entonces se pueden incluir usando:
|
|
//!
|
|
//! ```rust,ignore
|
|
//! include_locales!(LOCALES_SAMPLE from "ruta/a/las/traducciones");
|
|
//! ```
|
|
|
|
use crate::html::{Markup, PreEscaped};
|
|
use crate::{global, hm, AutoDefault};
|
|
|
|
pub use fluent_templates;
|
|
pub use unic_langid::{CharacterDirection, LanguageIdentifier};
|
|
|
|
use unic_langid::langid;
|
|
|
|
use fluent_templates::Loader;
|
|
use fluent_templates::StaticLoader as Locales;
|
|
|
|
use std::borrow::Cow;
|
|
use std::collections::HashMap;
|
|
use std::sync::LazyLock;
|
|
|
|
use std::fmt;
|
|
|
|
// Asocia cada código de idioma (como "en-US") con su respectivo [`LanguageIdentifier`] y la clave
|
|
// en *locale/.../languages.ftl* para obtener el nombre del idioma según la localización.
|
|
static LANGUAGES: LazyLock<HashMap<&str, (LanguageIdentifier, &str)>> = LazyLock::new(|| {
|
|
hm![
|
|
"en" => ( langid!("en-US"), "english" ),
|
|
"en-GB" => ( langid!("en-GB"), "english_british" ),
|
|
"en-US" => ( langid!("en-US"), "english_united_states" ),
|
|
"es" => ( langid!("es-ES"), "spanish" ),
|
|
"es-ES" => ( langid!("es-ES"), "spanish_spain" ),
|
|
]
|
|
});
|
|
|
|
// Identificador del idioma de **respaldo** (predefinido a `en-US`).
|
|
//
|
|
// Se usa cuando el valor del código de idioma en las traducciones no corresponde con ningún idioma
|
|
// soportado por la aplicación.
|
|
static FALLBACK_LANGID: LazyLock<LanguageIdentifier> = LazyLock::new(|| langid!("en-US"));
|
|
|
|
// Identificador del idioma **por defecto** para la aplicación.
|
|
//
|
|
// Se resuelve a partir de [`global::SETTINGS.app.language`](global::SETTINGS). Si el código de
|
|
// idioma configurado no es válido o no está disponible entonces resuelve como [`FALLBACK_LANGID`].
|
|
pub(crate) static DEFAULT_LANGID: LazyLock<&LanguageIdentifier> =
|
|
LazyLock::new(|| LangMatch::langid_or_fallback(&global::SETTINGS.app.language));
|
|
|
|
/// Comprueba si el idioma está soportado por `PageTop`.
|
|
///
|
|
/// Útil para transformar un código de idioma en un [`LanguageIdentifier`] válido para `PageTop`.
|
|
#[derive(Clone, Debug, Eq, PartialEq)]
|
|
pub enum LangMatch {
|
|
/// Cuando el código del idioma es una cadena vacía.
|
|
Empty,
|
|
/// Si encuentra un [`LanguageIdentifier`] que coincide exactamente o retrocediendo al idioma
|
|
/// base.
|
|
Found(&'static LanguageIdentifier),
|
|
/// Si el código del idioma no está entre los soportados por `PageTop`.
|
|
Unknown(String),
|
|
}
|
|
|
|
impl LangMatch {
|
|
/// Resuelve `language` y devuelve el [`LangMatch`] apropiado.
|
|
pub fn resolve(language: impl AsRef<str>) -> Self {
|
|
let language = language.as_ref().trim();
|
|
|
|
// Rechaza cadenas vacías.
|
|
if language.is_empty() {
|
|
return Self::Empty;
|
|
}
|
|
|
|
// Intenta aplicar coincidencia exacta con el código completo (p.ej. "es-MX").
|
|
if let Some(langid) = LANGUAGES.get(language).map(|(langid, _)| langid) {
|
|
return Self::Found(langid);
|
|
}
|
|
|
|
// Si la variante regional no existe, retrocede al idioma base (p.ej. "es").
|
|
if let Some((base_lang, _)) = language.split_once('-') {
|
|
if let Some(langid) = LANGUAGES.get(base_lang).map(|(langid, _)| langid) {
|
|
return Self::Found(langid);
|
|
}
|
|
}
|
|
|
|
// Devuelve desconocido si el idioma no está soportado.
|
|
Self::Unknown(language.to_string())
|
|
}
|
|
|
|
/// Devuelve siempre un [`LanguageIdentifier`] válido.
|
|
///
|
|
/// Si `language` está vacío o es desconocido, devuelve el idioma de respaldo ("en-US").
|
|
#[inline]
|
|
pub fn langid_or_fallback(language: impl AsRef<str>) -> &'static LanguageIdentifier {
|
|
match Self::resolve(language) {
|
|
Self::Found(l) => l,
|
|
_ => &FALLBACK_LANGID,
|
|
}
|
|
}
|
|
|
|
/// Devuelve un [`LanguageIdentifier`] válido para la instancia.
|
|
///
|
|
/// Si `language` está vacío o es desconocido, devuelve el idioma de respaldo ("en-US").
|
|
#[inline]
|
|
pub fn as_langid(&self) -> &'static LanguageIdentifier {
|
|
match self {
|
|
LangMatch::Found(l) => l,
|
|
_ => &FALLBACK_LANGID,
|
|
}
|
|
}
|
|
}
|
|
|
|
#[macro_export]
|
|
/// Define un conjunto de elementos de localización y textos de traducción local.
|
|
macro_rules! include_locales {
|
|
// Se eliminan las marcas de aislamiento Unicode en los argumentos para mejorar la legibilidad y
|
|
// la compatibilidad en ciertos contextos de renderizado.
|
|
( $LOCALES:ident $(, $core_locales:literal)? ) => {
|
|
$crate::locale::fluent_templates::static_loader! {
|
|
static $LOCALES = {
|
|
locales: "src/locale",
|
|
$( core_locales: $core_locales, )?
|
|
fallback_language: "en-US",
|
|
// Elimina marcas de aislamiento Unicode en los argumentos.
|
|
customise: |bundle| bundle.set_use_isolating(false),
|
|
};
|
|
}
|
|
};
|
|
( $LOCALES:ident from $dir_locales:literal $(, $core_locales:literal)? ) => {
|
|
$crate::locale::fluent_templates::static_loader! {
|
|
static $LOCALES = {
|
|
locales: $dir_locales,
|
|
$( core_locales: $core_locales, )?
|
|
fallback_language: "en-US",
|
|
// Elimina marcas de aislamiento Unicode en los argumentos.
|
|
customise: |bundle| bundle.set_use_isolating(false),
|
|
};
|
|
}
|
|
};
|
|
}
|
|
|
|
include_locales!(LOCALES_PAGETOP);
|
|
|
|
// Operación de localización a realizar.
|
|
//
|
|
// * `None` - No se aplica ninguna localización.
|
|
// * `Text` - Con una cadena literal que se devolverá tal cual.
|
|
// * `Translate` - Con la clave a resolver en el `Locales` indicado.
|
|
#[derive(AutoDefault)]
|
|
enum L10nOp {
|
|
#[default]
|
|
None,
|
|
Text(String),
|
|
Translate(String),
|
|
}
|
|
|
|
/// Crea instancias para traducir textos localizados.
|
|
///
|
|
/// Cada instancia puede representar:
|
|
///
|
|
/// - Un texto puro (`n()`) que no requiere traducción.
|
|
/// - Una clave para traducir un texto de las traducciones por defecto de `PageTop` (`l()`).
|
|
/// - Una clave para traducir de un conjunto concreto de traducciones (`t()`).
|
|
///
|
|
/// Los argumentos dinámicos se añaden mediante `with_arg()` o `with_args()`.
|
|
///
|
|
/// ```rust
|
|
/// use pagetop::prelude::*;
|
|
///
|
|
/// // Texto literal sin traducción.
|
|
/// let raw = L10n::n("© 2025 PageTop").get();
|
|
///
|
|
/// // Traducción simple con clave y argumentos.
|
|
/// let hello = L10n::l("greeting")
|
|
/// .with_arg("name", "Manuel")
|
|
/// .markup();
|
|
/// ```
|
|
///
|
|
/// También para traducciones a idiomas concretos.
|
|
///
|
|
/// ```rust,ignore
|
|
/// // Traducción con clave, conjunto de traducciones y código de idioma a usar.
|
|
/// let bye = L10n::t("goodbye", &LOCALES_CUSTOM).using(LangMatch::langid_or_fallback("it"));
|
|
/// ```
|
|
#[derive(AutoDefault)]
|
|
pub struct L10n {
|
|
op: L10nOp,
|
|
#[default(&LOCALES_PAGETOP)]
|
|
locales: &'static Locales,
|
|
args: HashMap<String, String>,
|
|
}
|
|
|
|
impl L10n {
|
|
/// **n** = *“native”*. Crea una instancia con una cadena literal sin traducción.
|
|
pub fn n(text: impl Into<String>) -> Self {
|
|
L10n {
|
|
op: L10nOp::Text(text.into()),
|
|
..Default::default()
|
|
}
|
|
}
|
|
|
|
/// **l** = *“lookup”*. Crea una instancia para traducir usando una clave de la tabla de
|
|
/// traducciones por defecto.
|
|
pub fn l(key: impl Into<String>) -> Self {
|
|
L10n {
|
|
op: L10nOp::Translate(key.into()),
|
|
..Default::default()
|
|
}
|
|
}
|
|
|
|
/// **t** = *“translate”*. Crea una instancia para traducir usando una clave de una tabla de
|
|
/// traducciones específica.
|
|
pub fn t(key: impl Into<String>, locales: &'static Locales) -> Self {
|
|
L10n {
|
|
op: L10nOp::Translate(key.into()),
|
|
locales,
|
|
..Default::default()
|
|
}
|
|
}
|
|
|
|
/// Añade un argumento `{$arg}` → `value` a la traducción.
|
|
pub fn with_arg(mut self, arg: impl Into<String>, value: impl Into<String>) -> Self {
|
|
self.args.insert(arg.into(), value.into());
|
|
self
|
|
}
|
|
|
|
/// Añade varios argumentos a la traducción de una sola vez (p.ej. usando la macro [`hm!`],
|
|
/// también vec![("k", "v")], incluso un array de duplas u otras colecciones).
|
|
pub fn with_args<I, K, V>(mut self, args: I) -> Self
|
|
where
|
|
I: IntoIterator<Item = (K, V)>,
|
|
K: Into<String>,
|
|
V: Into<String>,
|
|
{
|
|
self.args
|
|
.extend(args.into_iter().map(|(k, v)| (k.into(), v.into())));
|
|
self
|
|
}
|
|
|
|
/// Resuelve la traducción usando el idioma por defecto de la aplicación. Devuelve `None` si no
|
|
/// aplica o no encuentra una traducción.
|
|
pub fn get(&self) -> Option<String> {
|
|
self.using(&DEFAULT_LANGID)
|
|
}
|
|
|
|
/// Resuelve la traducción usando el [`LanguageIdentifier`] indicado. Devuelve `None` si no
|
|
/// aplica o no encuentra una traducción.
|
|
pub fn using(&self, langid: &LanguageIdentifier) -> Option<String> {
|
|
match &self.op {
|
|
L10nOp::None => None,
|
|
L10nOp::Text(text) => Some(text.to_owned()),
|
|
L10nOp::Translate(key) => self.locales.try_lookup_with_args(
|
|
langid,
|
|
key,
|
|
&self.args.iter().fold(HashMap::new(), |mut arg, (k, v)| {
|
|
arg.insert(Cow::Owned(k.clone()), v.to_owned().into());
|
|
arg
|
|
}),
|
|
),
|
|
}
|
|
}
|
|
|
|
/// Traduce y escapa con el idioma por defecto, devolviendo [`Markup`].
|
|
pub fn markup(&self) -> Markup {
|
|
PreEscaped(self.get().unwrap_or_default())
|
|
}
|
|
|
|
/// Traduce y escapa con el [`LanguageIdentifier`] indicado, devolviendo [`Markup`].
|
|
pub fn escaped(&self, langid: &LanguageIdentifier) -> Markup {
|
|
PreEscaped(self.using(langid).unwrap_or_default())
|
|
}
|
|
}
|
|
|
|
impl fmt::Display for L10n {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
let content = match &self.op {
|
|
L10nOp::None => String::new(),
|
|
L10nOp::Text(text) => text.clone(),
|
|
L10nOp::Translate(key) => self.get().unwrap_or_else(|| format!("??<{}>", key)),
|
|
};
|
|
write!(f, "{content}")
|
|
}
|
|
}
|