Fandom Developers Wiki
Advertisement

I18n-js es una biblioteca para cargar los mensajes de un script, almacenados como JSON, listos para su uso. No solo permite que los mensajes se separen del código principal, sino que también controla los errores de lenguaje y el análisis básico.

Uso[]

Página I18n[]

Para usar I18n-js, deberá configurar sus mensajes en el lugar apropiado y en el formato correcto. El cargador de mensajes esperará que sus mensajes estén en una página como MediaWiki:Custom-<PAGENAME>/i18n.json aquí en Fandom Developers Wiki, donde <PAGENAME> debería corresponder al nombre de su script. El formato de sus mensajes debe ser el siguiente:

{
    "en": {
        "name": "value"
    },
    "pl": {
        "name": "wartość"
    }
}

Sin embargo, editar JSON puede ser difícil, incluso para los veteranos. La forma ideal de crear una página /i18n.json es navegar a Special:BlankPage/I18nEdit/<PAGENAME>/en y utilizar el editor dedicado.

Importando el script[]

Cuando esté todo configurado, simplemente importe MediaWiki:I18n-js/code.js en su script. Hay algunas formas de hacerlo, pero generalmente se usa una de estas dos maneras:

1. Importe el script utilizando importArticles u otra función de importación que no proporciona ninguna indicación de cuándo el script ha terminado de cargarse. Si usa este método, puede escuchar el evento dev.i18n usando mw.hook:

// registra el hook antes de la importación para evitar condicionantes en la ejecución
mw.hook('dev.i18n').add(function (i18n) {
    // i18n es un acceso directo a window.dev.i18n
});

importArticle({ type: 'script', article: 'u:dev:MediaWiki:I18n-js/code.js' });

2. Importe el script mediante una función que proporcione una retrollamada, como $.getScript. Si está utilizando este método, utilice la retrollamada y acceda a window.dev.i18n dentro de:

$.getScript('https://dev.fandom.com/load.php?mode=articles&articles=MediaWiki:I18n-js/code.js&only=scripts')
    .done(function() {
        // aquí accede a window.dev.i18n
    });

Cargando sus mensajes[]

Ahora que el script está cargado, está listo para cargar sus mensajes. Esto se consigue usando el método loadMessages de window.dev.i18n que devuelve una instancia de i18n. Esto también almacenará en caché dicha instancia en caso de que intente cargar los mensajes nuevamente por cualquier motivo:

// name es la parte PAGENAME de https://dev.fandom.com/wiki/Custom-PAGENAME/i18n.json
i18n.loadMessages(name).done(function (i18n) {
    // use your i18n instance here
});

El método loadMessages también acepta un objeto opcional options como segundo argumento, que puede incluir las siguientes propiedades:

cacheAll
An array of message names for which translations should be cached for all languages. See §Message caching for details.
cacheVersion
La versión mínima de caché de mensajes solicitada por el script de carga. Consulte §Almacenamiento en caché de mensajes para obtener más detalles.
language
Establezca un idioma predeterminado para que use el script, en vez de usar wgUserLanguage. Tenga en cuenta que esto también afecta a las llamadas a useUserLang() y inUserLang().
noCache
Nunca cargue los mensajes de i18n desde la caché (esto no se recomienda para uso general).

Almacenamiento en caché de mensajes[]

Los mensajes cargados se almacenarán en la caché en el almacenamiento del navegador hasta dos días después de su carga, para mejorar la capacidad de respuesta en futuras cargas de página (ya que el script no tendrá que esperar a que los mensajes se carguen cada vez). Sin embargo, esto significa que su secuencia de comandos puede usar mensajes que tienen hasta dos días de antigüedad. Los mensajes en caché también incluyen un número de versión predeterminada a 0 (cero).

Si se añade un mensaje nuevo en una actualización de secuencia de comandos, es posible que sea necesario actualizar la caché para evitar que falten mensajes antes de la expiración de la caché de dos días. Para hacer esto, puede usar la opción cacheVersion en su llamada loadMessages. Si se utiliza la opción cacheVersion, se comparará con el número de versión en caché, y si el número de versión en caché es menor que la versión solicitada, la caché se actualizará y el número de versión en caché se establecerá en la versión solicitada.

Uso de i18n[]

i18n controla el acceso a tus mensajes individuales, así como el idioma al que intenta traducirlo. Define los siguientes métodos:

useContentLang()
Establece el idioma predeterminado en el valor wgContentLanguage.
useUserLang()
Establece el idioma predeterminado en el valor wgUserLanguage.
inContentLang()
Establece el idioma en el valor de wgContentLanguage, solo para el siguiente mensaje.
inUserLang()
Establece el idioma en el valor wgUserLanguage solo para el siguiente mensaje.
inLang(code)
Set the language to code for the next message only. This method is only functional if the cacheAll option has been configured - see §Message caching for details.
msg(message, arg1, arg2, arg3, ...)
Crea una instancia Message que represente el mensaje en el idioma más cercano posible al idioma predeterminado con cualquier argumento sustituido. Consulte §Uso del mensaje para obtener detalles sobre cómo usarlo.

Uso de mensajes[]

Message representa un mensaje traducido en el idioma más cercano al idioma predeterminado establecido en la instancia i18n como sea posible. Si no se pudo encontrar una traducción en el idioma solicitado, intentará un idioma alternativo en su lugar, hasta que vuelva al inglés. Si no se pudo encontrar la traducción al inglés, entonces contendrá el nombre del mensaje envuelto < ... >, por ejemplo <MESSAGE>.

Si tu mensaje utiliza argumentos, éstos deben especificarse en la forma $n donde n es un número entero mayor que 0, por ejemplo, 'Hello, $1, my name is $2'.

Hay tres métodos disponibles para generar el mensaje almacenado en la instancia Message:

plain()
Esto genera el mensaje tal cual sin estar procesado.
escape()
Esto genera el mensaje con cualquier carácter HTML de escape.
parse()
Esto genera el mensaje con todos los enlaces de wikitexto básicos convertidos a HTML y algunas palabras mágicas locales-específicas analizadas. También es compatible con la etiquetas en línea <i>, <b>, <em>, <strong> y <span> y los atributos title, style y class. Tenga en cuenta que las etiquetas no permitidas se eliminarán junto con su contenido, los atributos no permitidos se eliminarán y los atributos de estilo url('...') causará que se elimine todo el atributo style. Se admite la siguiente sintaxis de wikitexto:
    • [url text]
    • [[pagename]]
    • [[pagename|text]]
    • {{PLURAL:count|singular|plural}} (mas info)])
    • {{GENDER:gender|masculine|feminine|neutral}} (mas info)])
      • Tenga en cuenta que los nombres de usuario no son compatibles; el argumento gender debe ser 'masculino', 'femenino' o cualquier otra cosa para neutral).

Cada instancia Message también tiene una propiedad:

exists
true si se encontró una traducción para el mensaje, sino false.

Si inContentLang o inUserLang están siendo utilizados, también se puede encadenar la llamada mensaje:

// comienza con el idioma del usuario (digamos inglés)
i18n.msg('hello-world').plain(); // Hello World!

// Salida en el idioma del contenido de la wiki para un solo mensaje
i18n.inContentLang().msg('hello-world').plain(); // Bonjour le monde !

// y de nuevo al inglés
i18n.msg('hello-world').plain(); // Hello World!

Editando tus mensajes[]

JSON puede ser un poco complicado de editar, especialmente si no está familiarizado con la sintaxis. Para mejorar la experiencia de edición, se puede encontrar un editor dedicado en Special:Blankpage/i18nedit.

Anular mensajes[]

A veces, un usuario final puede desear personalizar un conjunto de mensajes de acuerdo con sus propias preferencias o incluso para una instalación en todo el sitio. Esto se puede lograr usando lo siguiente:

// en un archivo user o site.js

// inicializa los objetos globales utilizados sin sobrescribir nada que ya exista
window.dev = window.dev || {};
window.dev.i18n = window.dev.i18n || {};
window.dev.i18n.overrides = window.dev.i18n.overrides || {};
window.dev.i18n.overrides['EJEMPLO'] = window.dev.i18n.overrides['EJEMPLO'] || {};

// personaliza los mensajes deseados
window.dev.i18n.overrides['EJEMPLO']['some-message'] = 'My customised message';
window.dev.i18n.overrides['EJEMPLO']['another-message'] = 'Another customised message';

EJEMPLO es el nombre que utiliza el cargador de mensajes para identificar desde dónde cargar el mensaje. Por ejemplo, para el nombre I18nEdit, la página sería u:dev:MediaWiki:Custom-I18nEdit/i18n.json. Por lo tanto, para personalizar los mensajes de I18nEdit, usaría lo siguiente:

window.dev = window.dev || {};
window.dev.i18n = window.dev.i18n || {};
window.dev.i18n.overrides = window.dev.i18n.overrides || {};
window.dev.i18n.overrides['I18nEdit'] = window.dev.i18n.overrides['I18nEdit'] || {};

window.dev.i18n.overrides['I18nEdit']['title'] = 'My new title';

Para encontrar el nombre de un mensaje, se puede utilizar el truco del código del lenguaje QQX. Para los scripts que utilizan I18n-js, el texto se mostrará como (i18njs-Example-some-message), donde Example es el nombre del script y some-message es el nombre del mensaje. Por ejemplo, el mensaje edit-language utilizado en I18nEdit mostraría (i18njs-I18nEdit-edit-language).

Dependents[]

List of dependents using this library

Registro de cambios[]

(out of date - see code page history for full log)
Date Description
07 December 2018 Added support for the GENDER magic word when parsing messages.
19 September 2018 Added message caching functionality.
28 August 2018 Removed support for inline comments in JSON pages.
16 August 2018 Fixed an XSS issue when parsing messages.

Added an exists property to Message instances.
Added support for the PLURAL magic word when parsing messages.
Added support for the qqx language code to show keys of used messages.

21 June 2018 Added support for temporary language changes on a per message basis.
01 June 2018 Added support for some inline tags and attributes when using Message.parse().
29 May 2018 Added message override support.
21 February 2017 Prevent the script loading multiples times and causing the cache to be lost.
16 February 2017 Switched to factory method instead of constructors.

Fixed argument handling to start at $1 instead of $0. Fixed link parsing for absolute URLs.

15 February 2017 Improved fallback behaviour to mirror that of MediaWiki.

Added argument handling. Added basic parsing functionality.

13 February 2017 Initial release.

Ver también[]

Advertisement