Plugin de Transliteración

Conversión de caracteres de diferentes idiomas

El plugin Transliterate es una extensión para Grav CMS. Añade filtros de Twig para transliterar y convertir texto a ASCII, facilitando el manejo de caracteres especiales, diacríticos y escrituras no latinas en tus plantillas de Grav.

Instalación

La instalación del plugin de Transliteración se puede realizar de tres maneras: el método de instalación mediante GPM (Grav Package Manager) te permite instalar el plugin rápidamente con un simple comando en la terminal, el método manual te permite hacerlo mediante un archivo zip, y el método a través del Admin Plugin te permite instalarlo directamente desde la interfaz de administración.

Instalación mediante GPM (Preferido)

Para instalar el plugin a través de GPM, abre la terminal de tu sistema (también llamada línea de comandos), navega hasta la raíz de tu instalación de Grav e introduce:

bin/gpm install transliterate

Esto instalará el plugin de Transliteración en el directorio /user/plugins de Grav. Sus archivos se encontrarán en /tu/sitio/grav/user/plugins/transliterate.

Instalación Manual

Para instalar el plugin manualmente, descarga la versión en zip de este repositorio y descomprímela en /tu/sitio/grav/user/plugins. Luego, renombra la carpeta a transliterate. Puedes encontrar estos archivos en GitHub o a través de GetGrav.org.

Ahora deberías tener todos los archivos del plugin en:

/tu/sitio/grav/user/plugins/transliterate

NOTA: Este plugin es un componente modular para Grav que puede requerir otros plugins para funcionar. Consulta su archivo blueprints.yaml en GitHub.

Admin Plugin

Si utilizas el Admin Plugin, puedes instalar el plugin directamente navegando al menú Plugins y haciendo clic en el botón Añadir.

Configuración

Antes de configurar este plugin, debes copiar el archivo user/plugins/transliterate/transliterate.yaml a user/config/plugins/transliterate.yaml y editar solo esa copia.

Aquí tienes la configuración por defecto y una explicación de las opciones disponibles:

enabled: true
custom_rules: 'Any-Latin; Latin-ASCII'
allowed_chars: 'A-Za-z0-9 \-_,.'

Opciones

  • enabled (booleano) – Determina si el plugin está activo. Establécelo en true para habilitar la transliteración, o en false para deshabilitarla.

  • custom_rules (cadena) – Define las reglas de transliteración utilizando la sintaxis de transliteración de ICU. El valor por defecto 'Any-Latin; Latin-ASCII' convierte caracteres de cualquier escritura a latín y luego reemplaza los caracteres latinos por su equivalente más cercano en ASCII. Puedes modificarlo según tus necesidades.

    • Ejemplos:
      • 'Any-Latin; Latin-ASCII': Convierte caracteres no latinos a latín y luego a ASCII.
      • 'Greek-Latin; Latin-ASCII': Convierte caracteres griegos a latín y luego a ASCII.
      • 'Cyrillic-Latin; Latin-ASCII': Convierte caracteres cirílicos a latín y luego a ASCII.

  • allowed_chars (cadena) – Un patrón de expresión regular que define qué caracteres están permitidos en la salida transliterada. La configuración por defecto 'A-Za-z0-9 \-_,.' permite letras mayúsculas y minúsculas, números, espacios, guiones, guiones bajos, comas y puntos.

    • Ejemplos:
      • 'A-Za-z0-9 \-_': Permite letras mayúsculas y minúsculas, números, espacios, guiones y guiones bajos.
      • 'A-Za-z0-9 \-_,.': Permite letras, números, espacios, guiones, guiones bajos, comas y puntos.

Ten en cuenta que si utilizas el Admin Plugin, se guardará un archivo con tu configuración llamado transliterate.yaml en la carpeta user/config/plugins/ una vez que guardes la configuración en el Admin.

Uso

El plugin de Transliteración proporciona dos filtros de Twig para manejar texto:

  1. transliterate: Convierte texto con caracteres especiales, diacríticos o escrituras no latinas en un equivalente basado en latín.
  2. to_ascii: Convierte texto a ASCII, eliminando todos los caracteres no ASCII (incluyendo símbolos y espacios).

Ejemplos

Transliteración Básica

{{ 'Café en París' | transliterate }}

Salida:

Cafe en Paris

Conversión a ASCII

{{ 'Café en París @#$%^&*()' | to_ascii }}

Salida:

Cafe en Paris

Usando Reglas de Transliteración Personalizadas

Puedes especificar reglas de transliteración personalizadas para tener más control sobre la salida. Por ejemplo:

{{ 'Café en París' | transliterate('Any-Latin; Latin-ASCII; [\\u0100-\\u017F] remove') }}

Salida:

Cafe en Paris

Configuración de Caracteres Permitidos

Puedes configurar qué caracteres están permitidos en la salida. Por ejemplo, para permitir comas y puntos:

{{ 'Café, en París.' | to_ascii }}

Salida:

Cafe, en Paris.

Combinando Filtros

Puedes encadenar los filtros para realizar transformaciones más avanzadas:

{{ 'Café en París' | transliterate | to_ascii }}

Salida:

Cafe en Paris

Usando Códigos Unicode en Reglas de Transliteración

En el ejemplo:

{{ 'Café en París' | transliterate('Any-Latin; Latin-ASCII; [\\u0100-\\u017F] remove') }}

La parte [\\u0100-\\u017F] es un rango de caracteres Unicode que se eliminarán durante el proceso de transliteración. A continuación, explicamos cómo funcionan estos códigos y cómo puedes usarlos en tus reglas personalizadas.

¿Qué son los Códigos Unicode?

Unicode es un estándar que asigna un número único (llamado "punto de código") a cada carácter, símbolo o emoji en todos los idiomas y sistemas de escritura. Los códigos Unicode se representan en formato hexadecimal, como U+0100 o U+017F.

  • Ejemplos:
    • U+00E9 representa la letra é (e con acento agudo).
    • U+0100 representa la letra Ā (A con macrón).
    • U+017F representa la letra ſ (s larga).

¿Qué significa [\\u0100-\\u017F]?

Este rango de caracteres Unicode incluye letras latinas extendidas con diacríticos, como:

  • Ā (U+0100)
  • ā (U+0101)
  • Ē (U+0112)
  • ē (U+0113)
  • Ī (U+012A)
  • ī (U+012B)
  • Ō (U+014C)
  • ō (U+014D)
  • Ū (U+016A)
  • ū (U+016B)
  • ſ (U+017F)

Al usar [\\u0100-\\u017F] remove, estás indicando que todos los caracteres en este rango deben ser eliminados del texto resultante.

Cómo Encontrar Más Códigos Unicode

Puedes consultar tablas de caracteres Unicode en los siguientes recursos:

  1. Tablas Oficiales de Unicode: unicode.org/charts
    • Aquí encontrarás todos los rangos de caracteres organizados por idioma y tipo.
  2. FileFormat.Info: fileformat.info
    • Un recurso útil para buscar caracteres específicos y sus códigos Unicode.
  3. Wikipedia: Lista de Caracteres Unicode
    • Una lista completa de caracteres Unicode con ejemplos.

Cómo Usar Códigos Unicode en Reglas Personalizadas

Puedes usar rangos de caracteres Unicode en reglas de transliteración para:

  1. Eliminar Caracteres Específicos:
    • Ejemplo: [\\u0100-\\u017F] remove elimina todas las letras latinas extendidas.
  2. Convertir Caracteres Específicos:
    • Ejemplo: [\\u00C0-\\u00FF] Latin-ASCII convierte letras latinas con diacríticos a ASCII.