Configuração administrativa

O OpenDataBio funciona sem serviços externos opcionais, mas administradores precisam decidir explicitamente sobre envio de e-mail, serviços taxonômicos, tradução assistida e os locales disponíveis aos usuários. Mantenha credenciais no arquivo de ambiente da instalação; nunca as versione no repositório.

Os templates de ambiente distribuídos deixam USER_TRANSLATION_PROVIDER e todas as credenciais de serviços vazios. Assim, instalações Apache, nginx e Docker não ativam tradução silenciosamente nem fazem chamadas externas. No instalador interativo para servidor direto, aceitar a resposta padrão não à pergunta opcional do Google mantém o recurso desabilitado. Só configure esses serviços depois de definir quem administrará credenciais, cotas e custos.

Depois de alterar .env ou .env.production, atualize a configuração:

php artisan optimize:clear
php artisan config:cache

Em produção com Docker, execute o Artisan no container da aplicação e use caminhos visíveis dentro desse container.

Google Cloud Translation

O OpenDataBio usa o Cloud Translation Advanced (v3) somente para conteúdo mantido pelos usuários nos formulários de edição. Textos da interface em lang/ não são enviados ao Google. O texto gerado preenche campos ausentes e deve ser revisado antes de salvar o registro. Jobs de importação nunca chamam o Google automaticamente.

O Google exige faturamento ativo mesmo quando o consumo permanece dentro de eventual crédito gratuito. Consulte os preços atuais, configure alerta de orçamento e restrinja cotas antes de habilitar o serviço.

1. Entre no console do Google Cloud.
2. Crie ou selecione um projeto e anote o ID do projeto.
3. Vincule uma conta de faturamento.
4. Em APIs e serviços, habilite Cloud Translation API.
5. Em IAM e administrador → Contas de serviço, crie uma conta exclusiva para o OpenDataBio.
6. Conceda a ela Usuário da API Cloud Translation (roles/cloudtranslate.user). Não conceda Proprietário, Editor, Administrador nem o papel de agente de serviço do Cloud Translation.
7. Crie uma chave JSON para a conta de serviço e faça o download. Guarde-a fora do repositório, legível pelo usuário do servidor web e não pelos demais usuários do sistema.
8. Configure:

USER_TRANSLATION_PROVIDER=google
GOOGLE_CLOUD_PROJECT=id-do-projeto-google
GOOGLE_TRANSLATION_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=/caminho/absoluto/google-translation.json
USER_TRANSLATION_MAX_CHARACTERS_PER_REQUEST=10000
USER_TRANSLATION_TIMEOUT=30

No Apache ou nginx, o arquivo e seus diretórios-pai precisam ser acessíveis ao usuário do PHP/servidor web. Um arranjo típico é:

sudo chgrp www-data /caminho/seguro/google-translation.json
sudo chmod 750 /caminho/seguro
sudo chmod 640 /caminho/seguro/google-translation.json

Em produção com Docker, coloque o arquivo no diretório não versionado docker-secrets/, monte-o somente para leitura e use o caminho interno:

GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/google-translation.json

Valide primeiro sem solicitação externa e depois com uma tradução curta:

php artisan translations:check --source=en --target=es
php artisan translations:check --source=en --target=es --live

Para desabilitar a tradução assistida, deixe USER_TRANSLATION_PROVIDER vazio.

Tropicos

O Tropicos Web Services exige uma chave pessoal em todas as solicitações.

Configurá-lo melhora a curadoria taxonômica, permitindo procurar e validar nomes botânicos publicados no Tropicos, em vez de depender somente da biblioteca local ou de outras fontes externas.

1. Abra a página de solicitação de chave do Tropicos.
2. Informe o contato e a finalidade de uso solicitados.
3. Guarde a chave emitida no ambiente:

MOBOT_API_KEY=sua-chave-api-tropicos

Sem a chave, o OpenDataBio continua funcionando e outros serviços taxonômicos configurados, principalmente o GBIF, ainda podem ser usados. Não exponha a chave no código cliente nem a versione.

E-mail

E-mail é usado para recuperação de senha, verificação opcional de endereço, solicitações de datasets e notificações de jobs. Instalações de produção devem usar uma conta SMTP dedicada ou um provedor transacional.

Sem e-mail funcional, administradores precisam atender recuperações de conta manualmente, usuários podem não receber decisões sobre pedidos de acesso e jobs longos não conseguem avisar com segurança quando exigem atenção.

MAIL_MAILER=smtp
MAIL_HOST=smtp.exemplo.org
MAIL_PORT=587
MAIL_USERNAME=opendatabio@exemplo.org
MAIL_PASSWORD=substitua-pelo-segredo
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=opendatabio@exemplo.org
MAIL_FROM_NAME="${APP_NAME}"
MAIL_VERIFY_PEER=true
MAIL_VERIFY_PEER_NAME=true
MAIL_ALLOW_SELF_SIGNED=false
EMAIL_VERIFICATION_ENABLED=false

Use a porta 465 e a criptografia exigida pelo provedor quando aplicável. Mantenha a verificação de certificados habilitada em produção. Só habilite EMAIL_VERIFICATION_ENABLED depois de testar envio e recuperação de senha. Os workers da fila precisam estar ativos para notificações enfileiradas.

Responsabilidades dos locales

O OpenDataBio mantém três conceitos separados:

• APP_LOCALE é o locale principal permanente e é sempre obrigatório no conteúdo traduzível.
• Locales de interface possuem todos os arquivos de tradução em lang/<codigo>/.
• Locales de conteúdo são idiomas nos quais usuários podem manter valores de UserTranslation; não exigem tradução da interface.

ODB_INTERFACE_LOCALES e ODB_CONTENT_LOCALES inicializam uma instalação nova. Em uma instalação existente, use Admin → Locales da aplicação ou:

php artisan locales:configure --interfaces=en,es,pt-br --content=en,es,pt-br
php artisan locales:audit

Adicionar um locale somente para conteúdo

1. Em Admin → Locales da aplicação, adicione um código normalizado, como fr ou es-mx, e um nome legível.
2. Habilite Conteúdo do usuário.
3. Não habilite Interface sem que lang/<codigo>/ esteja completo.
4. Adicione um mapeamento em config/user-translation.php se o provedor não aceitar diretamente o código usado pela aplicação.

Registros existentes não são preenchidos automaticamente. Usuários podem abrir os formulários de edição e gerar explicitamente traduções ausentes. Importações em lote precisam fornecer suas traduções explicitamente.

Adicionar um novo locale de interface

1. Copie toda a estrutura de chaves de um diretório lang/<codigo>/ existente para lang/<novo-codigo>/.
2. Traduza cada valor no contexto da aplicação sem alterar chaves, placeholders, estrutura HTML ou sintaxe de pluralização.
3. Adicione o nome do locale em config/languages.php.
4. Execute a auditoria de locales e os testes da aplicação.
5. Implante o código contendo os arquivos de tradução.
6. Adicione/habilite o locale pela página administrativa ou por locales:configure.
7. Limpe os caches. Reconstrua resources/api/odb_param_schema.json usando seu gerador ao publicar mudanças de documentação/schema; nunca edite o JSON gerado manualmente.

Ao atualizar o OpenDataBio, compare o novo .env.example com o ambiente implantado, execute as migrations, rode php artisan locales:audit e atualize cada diretório lang/<codigo>/ instalado com novas chaves antes de habilitar a interface.