Administrator configuration

OpenDataBio works without optional external services, but administrators must make explicit decisions about e-mail delivery, taxonomic services, assisted translation and the locales available to users. Keep credentials in the installation environment file; never commit them to the source repository.

The shipped environment templates leave USER_TRANSLATION_PROVIDER and all service credentials empty. Apache, nginx and Docker installation therefore do not silently enable translation or make an external request. During the interactive direct-server installer, answering the optional Google question with its default no keeps the feature disabled. Configure services only after deciding who will manage credentials, quotas and operating costs.

After changing .env or .env.production, refresh the application configuration:

php artisan optimize:clear
php artisan config:cache

For Docker production, run Artisan inside the application container and use paths as seen inside that container.

Google Cloud Translation

OpenDataBio uses Cloud Translation Advanced (v3) only to translate user-maintained content in edit forms. Interface strings under lang/ are not sent to Google. Generated text fills missing fields and must be reviewed before the record is saved. Import jobs never invoke Google automatically.

Google requires billing even when usage remains within an applicable free credit. Review current pricing, set a budget alert, and restrict quotas before enabling the service.

1. Sign in to the Google Cloud console.
2. Create or select a project and record its project ID.
3. Link a billing account.
4. Under APIs & Services, enable Cloud Translation API.
5. Under IAM & Admin → Service Accounts, create a dedicated service account for OpenDataBio.
6. Grant that service account Cloud Translation API User (roles/cloudtranslate.user). Do not grant Owner, Editor, Admin, or the Cloud Translation service-agent role.
7. Create a JSON key for the service account and download it once. Store it outside the repository, readable by the web-server user and not by other system users.
8. Configure:

USER_TRANSLATION_PROVIDER=google
GOOGLE_CLOUD_PROJECT=your-google-project-id
GOOGLE_TRANSLATION_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=/absolute/server/path/google-translation.json
USER_TRANSLATION_MAX_CHARACTERS_PER_REQUEST=10000
USER_TRANSLATION_TIMEOUT=30

For Apache or nginx, the credential file and all parent directories must be accessible to the PHP/web-server user. A typical permission arrangement is:

sudo chgrp www-data /secure/path/google-translation.json
sudo chmod 750 /secure/path
sudo chmod 640 /secure/path/google-translation.json

For Docker production, place the file under the untracked docker-secrets/ directory, mount it read-only, and set the environment value to its container path, for example:

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

Verify configuration first without an external request, then with a short live translation:

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

Disable assisted translation at any time by leaving USER_TRANSLATION_PROVIDER empty.

Tropicos

Tropicos Web Services requires a personal API key in every request.

Configuring it improves taxonomic curation by allowing editors to search and validate published botanical names against Tropicos instead of relying only on the local library or other external sources.

1. Open the Tropicos API-key request page.
2. Submit the requested contact and intended-use information.
3. Store the issued key in the installation environment:

MOBOT_API_KEY=your-tropicos-api-key

If no key is configured, OpenDataBio remains functional and other configured taxonomic services, primarily GBIF, can still be used. Do not expose the key in client-side code or commit it.

E-mail

E-mail is used for password recovery, optional address verification, dataset requests and job notifications. Production installations should use a dedicated SMTP account or transactional provider.

Without working e-mail, administrators must support account recovery manually, users can miss access-request decisions and long-running background work cannot reliably notify them when attention is required.

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.org
MAIL_PORT=587
MAIL_USERNAME=opendatabio@example.org
MAIL_PASSWORD=replace-with-secret
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=opendatabio@example.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 port 465 with the encryption required by your provider when applicable. Keep certificate verification enabled in production. Enable EMAIL_VERIFICATION_ENABLED only after outbound delivery and password recovery have been tested. Queue workers must be running for queued notifications.

Locale responsibilities

OpenDataBio keeps three concepts separate:

• APP_LOCALE is the permanent primary locale and is always required for translatable content.
• Interface locales have complete application translation files under lang/<code>/.
• Content locales are languages in which users may maintain UserTranslation values. They do not require an interface translation.

ODB_INTERFACE_LOCALES and ODB_CONTENT_LOCALES initialize a new installation. For an existing installation, use Admin → Application locales or:

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

Add a content-only locale

1. In Admin → Application locales, add a normalized code such as fr or es-mx and a human-readable name.
2. Enable User content.
3. Do not enable Interface unless lang/<code>/ is complete.
4. Add a provider mapping in config/user-translation.php if the translation provider does not accept the application code directly.

Existing records are not automatically backfilled. Users may open their edit forms and explicitly generate missing translations. Bulk imports must supply their translations explicitly.

Add a new interface locale

1. Copy the complete key structure from an existing lang/<code>/ directory into lang/<new-code>/.
2. Translate every value in application context without changing keys, placeholders, HTML structure, or pluralization syntax.
3. Add the locale name to config/languages.php.
4. Run the locale audit and application tests.
5. Deploy the code containing the translation files.
6. Add/enable the locale through the admin page or locales:configure.
7. Clear caches. Rebuild resources/api/odb_param_schema.json with its generator when releasing documentation/schema changes; never edit the generated JSON manually.

When upgrading OpenDataBio, compare the new .env.example with the deployed environment, run database migrations, run php artisan locales:audit, and update every installed lang/<code>/ directory with any newly introduced translation keys before enabling that interface.