Como conectar o teu plugin con Lingvo?

Hai varios xeitos de facelo, dependendo de se queres deixar que Lingvo se encargue de todo ou queres empregar o teu propio código.

Engadindo a biblioteca

En primeiro lugar terás que engadir Lingvo.jar como biblioteca do teu plugin, do mesmo xeito que engadiches a biblioteca de Bukkit.jar.

Precisarás gardar o obxecto tradutor (com.github.coegho.lingvo.api.ITranslator) nalgunha parte do teu plugin. Un bo sistema é gardalo na propia clase principal (a que herda de JavaPlugin). Declara un obxecto coa interface ITranslator co seguinte código dentro da clase:

private ITranslator translator;

E engade un método para poder pedilo:

public ITranslator getTranslator() {

return translator;

}

Sempre que precises mandarlle unha mensaxe a un usuario, para obter a traducción só precisarás usar o seguinte comando:

plugin.getTranslator().translate(nomeDoUsuario, claveDaMensaxe);

Onde plugin é o teu plugin, nomeDoUsuario o nome do usuario que recibirá a mensaxe, e claveDaMensaxe a clave que direcciona á mensaxe correcta dentro do ficheiro de lingua.

En segundo lugar, podes decidir entre facer o teu plugin dependente de Lingvo (solución fácil), ou independente (máis difícil).

Dependente de Lingvo

Modifica o ficheiro plugin.yml e engade a seguinte liña:

depend: [Lingvo]

Facendo o plugin dependente asegúraste de que nunca se executará no servidor se Lingvo non está presente (se sucede isto, dará unha mensaxe de erro na consola). Isto permíteche escribir todo o teu código baseándote na premisa de que Lingvo sempre vai estar no servidor, polo que non precisas codificar clases alternativas para manexar os ficheiros de lingua no caso de que falte. Lembra comunicarlle aos usuarios do teu plugin que precisan descargar Lingvo na súa carpeta de plugins para que o teu plugin funcione correctamente.

Por último engade no método onEnable do teu plugin:

Lingvo lingvo = (Lingvo)this.getServer().getPluginManager().getPlugin("Lingvo");

Independente de Lingvo (para desenvolvedores con máis experiencia)

Isto permite que o teu plugin siga funcionando no caso de que Lingvo non estea presente, pero terás que ofrecer unha alternativa no código cando isto suceda. Modifica o ficheiro plugin.yml e engade a seguinte liña:

softdepend: [Lingvo]

Dentro do código, no método onEnable do teu plugin escribe o seguinte código:

JavaPlugin test = this.getServer().getPluginManager().getPlugin("Lingvo");

if(test != null) {

Lingvo lingvo = (Lingvo) test;

Código a executar se atopa Lingvo

} else {

Código se non se atopa

}

Se Lingvo está no servidor, executarase o código de dentro do if, e en caso contrario non. Unha boa solución sería empregar un booleano hasLingvo. Lembra non empregar clases nin métodos de Lingvo sen comprobar antes se Lingvo está presente no servidor.

Métodos para ler os ficheiros de lingua

Lingvo por defecto está preparado para procesar ficheiros YAML (de extensión .yml). Non obstante, se prefires usar as túas propias clases para facelo (sexa porque non che gusta o modo no que o fai Lingvo ou porque xa tiñas clases que se encargaban disto antes), podes facelo sen problemas empregando as interfaces correspondentes.

Usando o ficheiro langs.yml (recomendado)

Este é o sistema que emprega o propio Lingvo para enviar as súas mensaxes ao usar o comando /lingvo.

Crea un ficheiro langs.yml (podes usar o que ven no propio .jar de Lingvo como referencia) cun contido cunha estrutura semellante á seguinte:

languages:

nome_da_lingua:

aliases: [alias1, alias2]

path: ruta_ao_ficheiro.yml

nome_de_outra_lingua:

aliases: []

path: outra_ruta_ao_ficheiro.yml

Cambiando os nomes en cursiva polos valores correspondentes. Engade os ficheiros nas rutas especificadas (deben estar en formato YAML; podes usar os ficheiros galego.yml, espanol.yml, english.yml e esperanto.yml que veñen no propio .jar de Lingvo como referencia). Lingvo non esixe que teñan unha estrutura concreta, pero lembra que todos os ficheiros terán que ter todos a mesma para poder pedir as mensaxes mediante as súas correspondentes claves. Podes obter información sobre YAML na seguinte ligazón: Configuration API Reference (Bukkit).

Xa no código, do teu programa, no método onEnable engade a seguinte liña:

try {

translator = lingvo.generateTranslator(this, rutaAoFicheiroLangs, linguaPorDefecto);

} catch(Exception ex) {

código se algo falla, por exemplo que non atope a lingua por defecto

}

Onde translator é a variable onde almacenarás a clase tradutora, lingvo é unha referencia ao plugin Lingvo (consulta a sección "Engadindo a biblioteca", máis arriba), rutaAoFicheiroLangs normalmente é "langs.yml" (aínda que podes chamar este ficheiro como queiras e situalo onde queiras) e linguaPorDefecto é o que o seu nome indica (por exemplo, "galego").

Deste xeito non tes que facer nada máis, o teu plugin xa está listo.

Deixando que enlace directamente por nome (non recomendado)

Para programadores especialmente preguiceiros, a clase Translator non precisa un ficheiro langs.yml.

Se o tradutor recibe a petición dunha lingua que non está na lista de langs.yml, tratará de detectalo directamente. Por exemplo, se un usuario ten a lingua "chines" e esa lingua non aparece en langs.yml, o tradutor buscará o ficheiro "chines.yml" no directorio do plugin. Se non o atopa, empregará a lingua por defecto.

Se Lingvo non atopa o ficheiro langs.yml, non gardará ningunha lingua e polo tanto o tradutor buscará directamente todas as linguas que se lle pidan polo seu nome. Desaconséllase este sistema xa que non permite empregar alias nin indicar rutas a ficheiros que non sexan no directorio raíz do plugin.

Empregando clases de carga de lingua personalizadas (avanzado)

Cada ficheiro de lingua é manexado por un obxecto coa interface ILanguageFile que implementa o método getTranslation. O tradutor contén pola súa parte un obxecto coa interface ILangsLoader, que mediante o método getLanguageFile devolve os ficheiros de lingua citados anteriormente.

Por defecto, o tradutor de Lingvo xa contén implementacións destas dúas interfaces para poder ler ficheiros YAML mediante o ficheiro langs.yml (como se explicou anteriormente). No caso de que queiras empregar obxectos propios, por exemplo porque os ficheiros non están en formato YAML senón noutro formato, ou porque non queres usar o ficheiro langs.yml para localizar as linguas senón que tes outro sistema, só tes que crear unha clase que implemente a interface ILangsLoader e outra que implemente a interface ILanguageFile.

Unha vez estean rematadas, envía o obxecto ILangsLoader como argumento ao crear o tradutor:

translator = lingvo.generateTranslator(this, rutaAoFicheiroLangs, linguaPorDefecto, obxectoILangsLoader);

Empregando unha clase tradutora personalizada (avanzado)

No caso de que desexes facer unha clase tradutora de cero, tes a posibilidade de facelo, pero suporía desaproveitar o esqueleto que proporciona a clase TranslatorFrame (a propia de Lingvo).

Para isto é necesario crear unha clase que implemente a interface ITranslator (com.github.coegho.lingvo.api.ITranslator). Esta interface só ten un método, translate(nomeDoXogador, claveDaMensaxe). Dentro deste método será necesario facer chamadas ao método getUserLangData().getLanguage(nomeDoXogador) do plugin Lingvo para obter a lingua do xogador que solicita a mensaxe, pero nun futuro intentará simplificarse.

Unha vez feita esta clase, na parte do código na que se empregaría a función generateTranslator(), agora hai que crear unha instancia do tradutor e empregar a seguinte instrución:

lingvo.setTranslator(this, tradutor);

Non usar a clase tradutora, simplemente recibir eventos (non recomendado)

Isto permite ao desenvolvedor avanzado empregar o seu sistema multi-lingua sen usar os métodos de Lingvo para xestionalo, pero aproveitar o comando /lingvo para detectar os cambios de lingua dos usuarios e deste modo coordinar o seu plugin cos demais. Lingvo emite un evento LanguageChangeEvent cada vez que un usuario cambia de idioma, o cal conta cos métodos getUser() e getLanguage() para obter o nome do usuario e a lingua que seleccionou, respectivamente.