Ajuda:Multilanguage module tools/ca

Aquest mòdul facilita la creació de mòduls per a plantilles multilingües (o la localització d'aquestes) que:

Facilita la localització (i18n) tant dels noms dels arguments passats com de les etiquetes o missatges utilitzats, per això crea llistes (vegi's més avall).
Ocasionalment és utilitzat per fer crides a Wikidata per tal de completar els seus elements si aquests no son entrats manualment, com és el cas de Mòdul:Global infobox tools utilitzat per a la creació d'infotaules multiligües.
Generació de llistes per facilitar la comprovació dels noms dels paràmetres advertint, així, a l'usuari de l'existència d'un paràmetre desconegut.
Generació del codi per a TemplateData.
Es pot definir el tipus de paràmetres entrats (cadena -l'habitual-, número enter, número -real-, booleà) que serà utilitzat per a la comprovació dels paràmetres entrats i la generació del codi per a TemplateData.
Permet disseny modular, amb arguments, etiquetes o missatges col·locats en altres mòduls.

Descripció

Compte: en les funcions descrites a continuació, un paràmetre acabat amb * vol dir que és opcional.

Comprovació de paràmetres de funcions

p.ChkFunc (func_name, params) S'utilitza en la depuració d'una funció, i així es pot donar un missatge d'error més acurat del que podria donar lua. Pot ser útil per fer verificacions de funcions públiques que puguin utilitzar creadors de mòduls basats en aquest mòdul. Igualment utilitzat en Module:Global infobox tools.

On:

func_name es el nom de la funció a comprovar
params és una taula de paràmetres, on cada element és {nom, valor, tipus}, i:
- El tipus pot ser qualsevol dels següents de la taula següent:

a	sense un tipus específic
b	booleà
f	funció
i	número enter
k	clau (una cadena amb valor)
n	número
s	cadena amb valor o no
t	taula
x	cadena amb valor

- afegint "r", llavors el paràmetre és obligatori

Exemple:

function p.CheckIdx_arglab (ModuleName, idx, omit_params, for_lua)
    MLMT.ChkFunc ("CheckIdx_arglab", {  -- El nom de la funció
       {"ModuleName",ModuleName,"xr"},  -- "xr": una cadena requerida
       {"idx",idx,"tr"},                -- "tr": una taula requerida
       {"omit_params",omit_params,"t"}, -- "t": una taula opcional
       {"for_lua",for_lua,"b"},         -- "b": un booleà opcional
       }
    )

Llavors una crida amb CheckIdx_arglab ("MyModule", "table") donaria el missatge Error de Lua: In a call to "CheckIdx_arglab" parameter #2 (= "idx") must be a table, but found "table".

Paràmetres prestablerts

Habitualment només per a infotaules multilingües.

p.arg = {
    demo = 'demo',
    item = 'item',
    lang = 'lang',
}

function p.DemoItemLang()

Variables i funcions d'idioma

p.lang = nil Es defineix quan s'estableix un valor per a |lang=, utilitzat en el cas de demostracions. En aquest cas es les següents funcions tenen sentit:

function p.LangsDifWriteDirect() = false Si l'idioma és diferent de l'actual, el valor retornat per defecte és false.
function p.WriteDirect() La direcció d'escriptura de l'idioma, el valor retornat per defecte és ltr.

p.compare_lang = 'en' Mostrarà en anglès (en, per defecte) les llistes d'etiquetes (labels) que utilitzin crides a Wikidata (que es defineixi el seu contingut en forma de propietat o qualificador).

function p.IsRTL (frame) Funció que determina si la direcció d'escriptura d'un idioma és de dreta a esquerra l'anterior des d'un frame i amb un idioma definit amb |lang=.

function p.IniLang (args) Inicialitza els valors anteriors.

Estructuració de la traducció

Tant paràmetres com etiquetes i missatges queden estructurats en dos taules:

Una en el mòdul principal (Module:AnyName), on es pot definir (si cal) propietats o qualificadors de Wikidata, altrament la traducció en (habitualment) anglès.
L'altre en el mòdul i18n (Module:AnyName/i18n), amb la traducció a l'idioma propi, altrament prendrà el valor de la taula del mòdul principal.

Quedant definides les claus (identificadors de cada element, o -keys-) en el mòdul items (Module:AnyName/items).

Ambdues taules haurien d'estar estructurades amb les següents denominacions de taules:

p.l = { 
	Args	= 'Args',
	Labels	= 'Labels',
	Msgs	= 'Msgs',
	Errors	= 'Errors',
}

Labels to define translatable strings
arguments or parameters
text to display usually
warning or information messages
error messages

Vegem-ho en un exemple referit als paràmetres:

A Mòdul:MLMT age 1/items es defineixen les etiquetes de cinc paràmetres.

p.k = {
    birth_year = 'birth_year',
    death_year = 'death_year',
    ---
    years = 'years',
    ---
    birth_after_today = 'birth_after_today',
    death_after_birth = 'death_after_today',
}

En els dos següents mòduls, cal encapçalar-los amb:

local MLMT     = require "Module:Multilang module tools"
local MLMT_A1i = require "Module:MLMT age 1/items"

Al mòdul principal (Mòdul:MLMT age 1) es defineixen els paràmetres i les seves denominacions. Important: un paràmetre pot tenir diverses denominacions, llavors queden definides aquestes en una taula.

local items = {
    [MLMT.k.Args] = {
        [A1i.k.birth_year] = {"birth_year",1},
        [A1i.k.death_year] = {"death_year",2},
    },	
    [MLMT.k.Labels] = {
        [A1i.k.years]	= "years",
    },
    [MLMT.k.Errors] = {
        [A1i.k.birth_after_today] = 'Birth year after current year',
        [A1i.k.death_after_birth] = 'Death year after birth year',
    },	
}

Al mòdul de traducció (Mòdul:MLMT age 1/i18n) s'assignaran les traduccions. Aquestes traduccions s'afegiran a les denominacions en anglès de l'anterior mòdul.

local items = {
    [MLMT.k.Args] = {
        [MLMT_A1i.k.birth_year]	= "any_naix",
        [MLMT_A1i.k.death_year]	= "any_mort",
    },	
    [MLMT.k.Labels] = {
        [MLMT_A1i.k.years] = "anys",
    },	
    [MLMT.k.Errors] = {
        [MLMT_A1i.k.birth_after_today] = "Any de naixement després de l'any en curs",
        [MLMT_A1i.k.death_after_birth] = "Any de la mort després de l'any de naixement",
    },	
}

Elements agrupats

A vegades en una llista molt llarga de paràmetres, etiquetes o missatges, per tal de tenir-los més delimitats, es poden agrupar. Aixó ho podeu veure en l'exemple Module:MLMT age 2, on s'agrupen els paràmetres (tot i que en aquest cas no tindria gaire sentit, en haver-hi pocs elements).

Quan s'utilitzen elements agrupats, s'ha de respectar l'agrupació en les llistes d'elements. Per a identificar-ho s'utilitza l'etiqueta "HasChild".

Mòduls compartits

Són mòduls que subministren paràmetres, etiquetes o missatges a diversos mòduls. Un exemple és el Module:Medical infobox items, que subministra alguns paràmetres a diferents mòduls d'infotaules.

tableMerge

Per afegir-les s'utilitzarà la funció: function p.tableMerge (ModuleName, tab_main, tab_lang). En aquest cas s'hauria d'afegir en el mòdul principal:

itemsM = MLMT.tableMerge (ModuleName, items, IIi18n.items)

On:

itemsM, és la taula resultant de la fusió.
IIi18n = require "Module:Infobox images/i18n"

tableMerge

Comprova que totes les traduccions fetes tinguin una correspondència en l'original en anglès. Així es fa una advertència si hi ha un element al mòdul i18n que no estigui al mòdul principal.
Si no hi ha un paràmetre en el mòdul i18n o aquest és buit (""), es pren el valor original.
En el cas de les etiquetes o missatges, lògicament, no s'afegiran sinó que se substituiran.

Comprovació de paràmetres

function p.CheckParamsM (args, ArgsPoss, OtherArgs*)

On ArgsPoss és una taula amb les taules de paràmetres. Si no s'utilitzen mòduls compartides, ArgsPoss serà una taula amb un sol element: la taula amb els paràmetres del mòdul.

On OtherArgs és una taula amb paràmetres acceptables que no posen en marxa la funcionalitat del mòdul, i que habitualment serveixen per obtenir llistes d'arguments amb |allitems=. En aquest últim cas OtherArgs = {"allitems"}.

Etiquetes

function p.GetLabelL (tab, key, lang)

function p.GetLabel (tab, key)

Llistes

{{#invoke:Nom del mòdul|funció principal|allitems=Possibilitat}}

On Possibilitat ha de ser:

params: Arguments o paràmetres possibles.
template: Presenta el codi del TemplateData, a copiar en la documentació de la plantilla que crida el mòdul.
labels: Taula amb la denominació de les etiquetes cridades a Wikidata, amb la seva correspondència en anglès i la traducció a l'idioma de la Viquipèdia. Amb |lang=, ofereix la traducció alternativa a la de la Viquipèdia: l'escollida. Permet enllaçar i completar les traduccions.
msgs: Missatges d'informació que complementen el resultat. El contingut no és assignable a una propietat o qualificador de Wikidata.
errors: Missatges d'error, pels quals habitualment s'aturarà el curs del programa i es presentarà el text d'error. El contingut no és assignable a una propietat o qualificador de Wikidata.

Segueix així:

p.LOpt = { 
	params	 = 'params',
	template = 'template', 
	labels	 = 'labels',
	msgs	 = 'msgs',
	errors	 = 'errors',
}

Display list options, id p.l

p.IT = {
    s	 = 's',
    i	 = 'i',
    ipos = 'i+',
    n	 = 'n',
    npos = 'n+',
    d	 = 'd',
    b	 = 'b',
    sz	 = 'sz',
    a	 = 'a',
}

tipus de paràmetre
cadena
número enter
número enter positiu
número
número positiu
data
booleà
mida
matriu

p.uses_QP_for_labels = false --if true appears in labels list a column with Qualifiers or Properties of Wikidata

Permet obtenir llistes dels paràmetres d'arguments, etiquetes o missatges que apareixen en un mòdul.

function p.all_items_opt (args, opt)

function p.add_mod_used (abbrev, name)

Les funcions principals de les llistes són similars i utilitzen el paràmetre opcional tab_modname_func quan hi han mòduls compartits. Aquest paràmetre és una taula de taules on cada subtaula fa referència a un dels mòduls compartits. Així si es comparteix "Mòdul:Compartit1", llavors tab_modname_func = {{"Compartit1", funcio_referida_a_Compartit1}}.

Llistes dels paràmetres i codi TemplateData

function p.show_arg_items (option, idx, func, tab_modname_func*)

On option és "param" o "template".
On idx és la llista de paràmetres (situada a /items).
On func és una funció (local, que s'ha de crear) que retorna: l'abreviatura del mòdul, la taula mestre, la taula traduïda (a /i18n), el tipus de paràmetre, si és requerit.
- L'abreviatura del mòdul serà utilitzada com a primera columna si hi han mòduls compartits, on cada mòdul tindrà una abreviatura. Si hi han mòduls compartits l'abreviatura amb el nom-enllaç als mòduls utilitzats apareixerà al final de la llista generada de paràmetres, altrament sols el nom/enllaç.
- El tipus de variable és un valor de p.IT (vegeu aquí), és opcional, i per defecte el valor és "s". Utilitzat a TemplateData. Per a determinar-lo es pot utilitzar:
  - function p.GetArgType (key, tab_int, tab_num, tab_date, tab_bool)
  - function p.GetArgTypeGrp (grp, key, tab_int, tab_num, tab_date, tab_bool), per paràmetres agrupats
- Si és requerit és opcional, i per defecte el valor és false. Utilitzat a TemplateData. Per a determinar-lo es pot utilitzar:
  - function p.GetRequired (key, tab)
  - function p.GetRequiredGrp (grp, key, tab), per paràmetres agrupats

Funcions per a mòduls compartits de paràmetres:

function p.add_arg_item (option, mod_abbrev, key, wd_main, wd_lang, lims)
function p.add_arg_item_grp (option, mod_abbrev, grp, key, wd_main, wd_lang, lims)

Llistes de les etiquetes

function p.show_lab_items (idx, func, tab_modname_func*)

On idx és la llista d'etiquetes (situada a /items).
On func és una funció (local, que s'ha de crear) que retorna: l'abreviatura del mòdul, la taula mestre, la taula traduïda (a /i18n). Utilitza GetLabelX.
- L'abreviatura del mòdul serà utilitzada com a primera columna si hi han mòduls compartits, on cada mòdul tindrà una abreviatura. Si hi han mòduls compartits l'abreviatura amb el nom-enllaç als mòduls utilitzats apareixerà al final de la llista generada d'etiquetes, altrament sols el nom/enllaç.

function p.GetLabelX (mod_abbrev, key, tab_main, tab_lang)

Funcions per a mòduls compartits d'etiquetes:

function p.add_lab_item (mod_abbrev, key, wd_main, wd_lang, lnk)
function p.add_lab_item_grp (mod_abbrev, grp, key, wd_main, wd_lang, lnk)

Llistes dels missatges normals i d'error

function p.show_msgs_errors (idx, func, tab_modname_func*)

On idx és la llista de missatges normals o d'error (situada a /items).
On func és una funció (local, que s'ha de crear) que retorna: l'abreviatura del mòdul, la taula mestre, la taula traduïda (a /i18n). Utilitza GetMsgErrorX.
- L'abreviatura del mòdul serà utilitzada com a primera columna si hi han mòduls contribuïdors, on cada mòdul tindrà una abreviatura. Si hi han mòduls contribuïdors l'abreviatura amb el nom-enllaç als mòduls utilitzats apareixerà al final de la llista generada de missatges, altrament sols el nom/enllaç.

function p.GetMsgErrorX (option, mod_abbrev, key, tab_main, tab_lang)

Funcions per a mòduls compartits de missatges:

function p.add_msg_error_item (mod_abbrev, key, wd_main, wd_lang)
function p.add_msg_error_item_grp (mod_abbrev, grp, key, wd_main, wd_lang)

Exemples