Pular para o conteúdo principal

Translate

Idiomas por jogador, arquivos de tradução, placas traduzidas e tradução de chat por IA opcional.

Privadasv0.2.0Utilitários
RequerTypeWriter0.9.0-beta-177 (BTC build)GUIopcionalMySQLopcionalMiniPlaceholdersopcional

Criada para a rede BornToCraft. Esta extensão é documentada como referência e não é distribuída.

Suporte

Visão geral​

O Translate permite que cada jogador escolha um idioma e leia o conteúdo do seu servidor nele. Você declara os idiomas em uma entry de configuração, escreve os textos em arquivos JSON (o formato é compatível com o plugin Triton, então arquivos existentes podem ser reaproveitados) e os exibe em qualquer lugar que aceite placeholders MiniMessage com <translate_key:your.key>. Cada jogador vê o texto no próprio idioma, com recurso a outro idioma quando um texto está ausente.

Três recursos opcionais complementam: placas traduzidas (uma placa mostra seu texto no idioma de quem a olha), um menu de idiomas e um menu de configurações construídos como pages GUI comuns e a tradução do chat por IA, em que as mensagens do chat são traduzidas para espectadores que falam outro idioma por meio de um provedor de IA ou de um mecanismo de tradução.

As escolhas dos jogadores são armazenadas em artifacts. O idioma é salvo por jogador, assim como as opções de aceitação da tradução de placas e do chat.

Recursos​

  • Lista de idiomas — cada idioma tem um código, uma bandeira de banner, nome de exibição, locales do cliente, fallbacks e ações a executar quando escolhido.
  • Arquivos JSON no estilo Triton — traduções de texto e de placas, com argumentos %1, %2, carregadas de uma pasta e recarregáveis sem reiniciar.
  • Cadeia de fallback — o idioma solicitado, depois seus fallbackLanguages e depois o idioma principal.
  • Detecção automática — troque opcionalmente para o idioma correspondente ao locale do cliente.
  • Placas traduzidas — coloque texto em coordenadas de placas; os jogadores podem desativar no menu de configurações.
  • Menus declarados por pages — construa os menus de idioma e de configurações como pages GUI com tipos de botão do Translate.
  • Tradução do chat por IA — OpenRouter, OpenAI, DeepSeek, Groq, Mistral, Ollama, Anthropic, Gemini, LibreTranslate, DeepL ou qualquer servidor compatível com OpenAI, com cache.
  • Eventos e facts de idioma — dispare entries quando um jogador troca de idioma e teste o idioma atual em criteria.

Instalação​

  1. Instale a extensão GUI para usar os menus de idioma e de configurações (opcional se você usar apenas o comando).
  2. Opcionalmente, instale a extensão MySQL: o cache de tradução por IA é então salvo no banco de dados; caso contrário, vive apenas na memória.
  3. Coloque o JAR do Translate em plugins/Typewriter/extensions/ e reinicie o servidor.
  4. Crie a pasta plugins/Typewriter/Translate/ (ela é criada automaticamente no primeiro carregamento) e coloque nela seus arquivos de tradução .json.
  5. Instale o MiniPlaceholders se quiser exibir traduções por placeholders.

Primeiros passos​

  1. No painel web do TypeWriter, abra uma page static e adicione um artifact Player Language: sem ele, o idioma escolhido não é salvo.
  2. Adicione uma entry Translation Config. Em languages, adicione en_GB e fr_FR: para cada um, defina name, flag (um código de banner), displayName (por exemplo &3Francais), minecraftCodes (fr_FR, fr_CA) e, opcionalmente, fallbackLanguages. Defina mainLanguage como en_GB.
  3. Crie plugins/Typewriter/Translate/messages.json com este conteúdo e depois publique ou execute /translate reload:
[
  {
    "type": "text",
    "key": "welcome.message",
    "languages": {
      "en_GB": "&6Welcome to the server, %1!",
      "fr_FR": "&6Bienvenue sur le serveur, %1 !"
    }
  }
]
  1. Use <translate_key:welcome.message> em qualquer texto MiniMessage com placeholders (um diálogo, um holograma, um scoreboard). Um jogador que executar /translate fr_FR agora vê o texto em francês.
  2. Para deixar os jogadores escolherem em um menu, construa uma page de menu com a extensão GUI, coloque nela itens translate_button:LANGUAGE#0, LANGUAGE#1..., referencie-a em languageMenu da configuração e dispare Open Language Selector.
observação

Os argumentos de texto %1, %2 só são preenchidos por código que chama a API de tradução com argumentos. O placeholder <translate_key:...> recebe apenas uma chave, então %1 permanece como escrito ali.

Como funciona​

O idioma de um jogador é resolvido nesta ordem: a escolha salva, depois o idioma correspondente ao locale do cliente (minecraftCodes) e depois mainLanguage.

Arquivos de tradução​

Os arquivos são arquivos .json diretamente na pasta de traduções (translationsFolder, Translate por padrão, dentro de plugins/Typewriter/). Cada arquivo é um array de itens; um arquivo também pode ser um objeto que contém esse array em translations, items, languages, data ou entries. Itens sem um type e um key válidos são ignorados, e um arquivo que falha ao ser interpretado é registrado no log e ignorado.

Um item text tem um key e um objeto languages. Os códigos de cor com & são convertidos. A busca de chaves é tolerante: a chave exata, depois a chave com os prefixos lang_, lang. ou default., depois sem diferenciar maiúsculas de minúsculas e depois uma correspondência com a parte após o último _ ou ..

Um item sign tem locations (world, x, y, z) e lines por idioma. Até 8 linhas são lidas, mas apenas as 4 primeiras (frente) são exibidas.

{
  "type": "sign",
  "key": "shop.sign",
  "locations": [{"world": "world", "x": 100, "y": 64, "z": 200}],
  "lines": {
    "en_GB": ["&b[Shop]", "&fClick to open", "", ""],
    "fr_FR": ["&b[Boutique]", "&fCliquez pour ouvrir", "", ""]
  }
}

Uma placa é traduzida quando um jogador a coloca ou edita em uma localização listada, ou clica nela com o botão direito; o jogador vê o idioma dele na placa por meio de uma atualização no lado do cliente. Os jogadores que desativaram a tradução de placas no menu de configurações veem o original.

Os menus de idioma e de configurações são entries open_gui normais da extensão GUI. O Translate fornece tipos de botão para colocar em seus itens (o campo de tipo de botão de um item do GUI):

Tipo de botãoComportamento
translate_button:LANGUAGE#<n>O n-ésimo idioma da configuração (a partir de 0). Mostra o código e um marcador no ativo; o clique esquerdo o seleciona. Vazio depois do último idioma.
translate_button:TOGGLE_CHATMostra e alterna a tradução do chat por IA do jogador (ativada por padrão).
translate_button:TOGGLE_SIGNMostra e alterna a tradução de placas do jogador (ativada por padrão).

Referencie as pages na Translation Config: languageMenu (e languageMenuViewId para uma view específica) para o seletor, settingsMenu (e settingsMenuViewId) para as configurações. Abra-as com Open Language Selector ou Open Translation Settings. /translate menu abre o menu de idiomas. Se openSelectorCommandOverride estiver definido, esse comando é executado pelo console no lugar ({player} é substituído pelo nome do jogador).

A seleção de idioma pelo menu precisa de um artifact Player Language: sem um, o jogador é avisado de que a escolha não seria salva. As alternâncias também precisam dos artifacts Player AI Preference e Player Sign Preference.

Tradução do chat por IA​

Configure aiTranslation na Translation Config. Defina enabled, escolha um provider e informe uma apiKey. A URL base e o modelo assumem, por padrão, os do provedor, a menos que apiBaseUrl ou model seja definido; OPENAI_COMPATIBLE exige apiBaseUrl. Prefira env:VAR_NAME como apiKey para ler a chave de uma variável de ambiente em vez de armazená-la na page.

Quando um jogador conversa, a mensagem é traduzida para o idioma de cada espectador cujo idioma difere do do remetente e que tem a tradução do chat ativada. O texto traduzido substitui a mensagem no chat do espectador, e passar o mouse sobre ele mostra o original. O chat espera no máximo chatTranslationTimeoutMs (800 ms por padrão) pelas traduções e então exibe a mensagem sem tradução aos espectadores que ainda aguardam. As mensagens que correspondem a noTranslateRegex (comandos e números puros por padrão) não são enviadas, o texto que corresponde a censorRegex é substituído por *** antes do envio, e enabledSections deve conter CHAT.

Após três requisições com falha consecutivas, a tradução por IA se desativa até o próximo recarregamento das traduções. Os resultados são armazenados em cache por mensagem e idioma, no banco de dados se a extensão MySQL estiver presente e na memória caso contrário.

Comandos​

O comando é /translate, com os aliases /lang e /language. Ele só pode ser executado por jogadores.

ComandoDescrição
/translateMostra a ajuda.
/translate <language>Define o seu idioma pelo nome configurado (por exemplo fr_FR).
/translate listLista os idiomas configurados e marca o seu.
/translate menuAbre o seletor de idiomas.
/translate toggle_aiAlterna a tradução do chat por IA para você.
/translate sign set <key>Marca a placa que você está olhando (a até 5 blocos) como traduzida com esta chave. Exige typewriter.translate.admin.
/translate sign removeRemove a marca da placa. Exige typewriter.translate.admin.
/translate sign infoMostra a chave, a localização e a tradução da placa. Exige typewriter.translate.admin.
/translate reloadRecarrega os arquivos de tradução. Exige typewriter.translate.admin.

/translate sign set apenas grava um marcador e a chave na placa. O texto de fato vem de um item sign em um arquivo JSON com a localização da placa.

Permissões​

PermissãoConcede
typewriter.translate.admin/translate reload e /translate sign ....

Placeholders​

Expansão translate do MiniPlaceholders, utilizável como tags MiniMessage. O texto traduzido pode conter marcação MiniMessage e placeholders aninhados.

PlaceholderRetorna
<translate_key:some.key>O texto dessa chave no idioma do espectador. Se ausente, [Translation not found: key] em vermelho.
<translate_lang>O código de idioma do espectador, como fr_FR.
<translate_lang_display>O nome de exibição do idioma.
<translate_lang_flag>O código da bandeira de banner do idioma.
<translate_count>Número de traduções carregadas (textos mais placas).
<translate_languages>Número de idiomas configurados.

Entries​

10 entradas, geradas a partir do código-fonte da extensão.

Ações4
Eventos1
Fatos1
Artefatos3
Manifestos1

Solução de problemas​

[Translation not found: key] aparece. A chave não está em nenhum arquivo carregado, ou o arquivo falhou ao carregar. Verifique no log do servidor se há Failed to load translation file, valide o JSON e execute /translate reload. Certifique-se de que o arquivo está diretamente em plugins/Typewriter/Translate/ (subpastas não são lidas) e tem a extensão .json.

O idioma é redefinido a cada login. Nenhum artifact Player Language está publicado, então a escolha não é armazenada. Adicione um.

O menu não faz nada. O log diz No 'languageMenu' configured ou No 'settingsMenu' configured: defina a page do menu na Translation Config. No menu de idiomas, openSelectorCommandOverride tem precedência quando não está vazio.

O idioma não acompanha o idioma do cliente. Sem uma escolha salva, o locale do cliente é usado automaticamente se aparecer em minecraftCodes de um idioma. forceClientLocaleOnJoin também troca o jogador, e sobrescreve a escolha salva dele, sempre que o cliente informa uma mudança de locale que corresponda a outro idioma.

A tradução por IA parou de funcionar. Procure AUTOMATICALLY DISABLED no log: três falhas consecutivas da API a desativam. Corrija a chave, a URL ou o modelo e depois execute /translate reload. apiKey references env var ... not set significa que a variável de ambiente está ausente.

Uma placa não é traduzida. A placa deve estar exatamente nas coordenadas listadas em um item sign de um arquivo JSON, com o nome de mundo correto. O jogador não deve ter desativado a tradução de placas, e a placa é traduzida quando colocada ou clicada com o botão direito.

Extensões relacionadas​

  • TinyEssentials — seu formato de chat é preservado quando a tradução por IA envolve o renderizador de chat.
  • MySQL — cache persistente da tradução por IA.