A internacionalização (i18n) é um pilar fundamental para o sucesso de aplicações globais, especialmente em plataformas de código aberto focadas em inteligência artificial generativa. Este guia técnico detalha a arquitetura de localização e o fluxo de trabalho para contribuidores que desejam adicionar novos idiomas a estúdios de geração de mídia baseados em IA, utilizando uma abordagem leve e eficiente em JavaScript.

Arquitetura de Internacionalização no Front-end

Em aplicações web modernas que não dependem de frameworks pesados, a gestão de idiomas pode ser centralizada em um módulo utilitário. O núcleo do sistema de tradução reside em um arquivo de configuração que gerencia o estado do idioma, a persistência no armazenamento local e o dicionário de strings.

Estrutura do Módulo de Idiomas

O módulo src/utils/localeManager.js encapsula a lógica de i18n. Ele define a chave de armazenamento, funções de acesso e o mapeamento de textos.

// src/utils/localeManager.js
const STORAGE_LOCALE_KEY = 'app_ui_locale';

const localeDictionary = {
  'en-US': {
    'ui.nav.images': 'Images',
    'ui.nav.videos': 'Videos',
    'ui.actions.generate': 'Generate',
    'ui.prompts.placeholder': 'Describe your vision...'
  },
  'pt-BR': {
    'ui.nav.images': 'Imagens',
    'ui.nav.videos': 'Vídeos',
    'ui.actions.generate': 'Gerar',
    'ui.prompts.placeholder': 'Descreva sua visão...'
  }
};

export function getCurrentLocale() {
  return localStorage.getItem(STORAGE_LOCALE_KEY) || 'en-US';
}

export function updateLocale(newLocale) {
  localStorage.setItem(STORAGE_LOCALE_KEY, newLocale);
  window.location.reload();
}

export function translate(key, fallback = '') {
  const lang = getCurrentLocale();
  return localeDictionary[lang]?.[key] || localeDictionary['en-US']?.[key] || fallback || key;
}

export function formatTranslation(key, ...params) {
  let text = translate(key);
  params.forEach((param, index) => {
    text = text.replace(`{${index}}`, param);
  });
  return text;
}

Fluxo de Trabalho para Adição de Novos Idiomas

1. Preparação do Ambiente Local

Comece clonando o repositório e configurando uma nova branch para sua contribuição de localização.

git clone git@github.com:open-gen-ai/media-studio.git
cd media-studio
git switch -c feat/add-spanish-locale

2. Expansão do Dicionário de Tradução

Para adicionar um novo idioma, como o espanhol (es-ES), insira um novo objeto no dicionário principal. Certifique-se de mapear todas as chaves existentes para evitar que a interface exiba as chaves brutas (fallback).

'es-ES': {
  'ui.nav.images': 'Imágenes',
  'ui.nav.videos': 'Videos',
  'ui.actions.generate': 'Generar',
  'ui.prompts.placeholder': 'Describe tu visión...'
}

3. Atualização dos Componentes de Interface

Os componentes de UI devem refletir o novo idioma no seletor de idiomas. Modifique o componente de cabeçalho para incluir a nova opção e ajustar a lógica de alternância.

// src/components/NavigationHeader.js
import { getCurrentLocale, updateLocale, translate } from '../utils/localeManager';

function renderLocaleSwitcher() {
  const switcherBtn = document.createElement('button');
  const activeLocale = getCurrentLocale();
  
  switcherBtn.classList.add('locale-toggle', 'btn-ghost');
  switcherBtn.setAttribute('aria-label', translate('ui.accessibility.change_lang'));
  
  const localeMap = {
    'en-US': { label: 'EN', next: 'pt-BR' },
    'pt-BR': { label: 'PT', next: 'es-ES' },
    'es-ES': { label: 'ES', next: 'en-US' }
  };

  const currentConfig = localeMap[activeLocale] || localeMap['en-US'];
  switcherBtn.textContent = currentConfig.label;
  
  switcherBtn.addEventListener('click', () => {
    updateLocale(currentConfig.next);
  });

  return switcherBtn;
}

4. Validação e Envio da Contribuição

Após testar a interface e verificar a integridade das strings interpoladas, prepare o commit seguindo as convenções do projeto.

git add src/utils/localeManager.js src/components/NavigationHeader.js
git commit -S -m "feat(i18n): add es-ES locale support and update switcher logic"
git push origin feat/add-spanish-locale

Diretrizes Técnicas para Tradução de Software

• Interpolação de Variáveis: Ao traduzir strings que utilizam formatTranslation, mantenha os marcadores de posição (ex: {0}) intactos. A ordem dos parâmetros pode mudar dependendo da gramática do idioma alvo.
• Limites de UI: Considere o comprimento do texto. Idiomas como o alemão podem expandir o comprimento da string em até 30% em comparação com o inglês, o que pode quebrar layouts flexbox ou grid se não houver tratamento adequado de text-overflow.
• Terminologia de IA: Mantenha a consistência técnica. Termos como "prompt", "inference", "weights" e "tokens" muitas vezes não são traduzidos ou possuem equivalentes específicos na comunidade de aprendizado de máquina.