# GenieHive Translation Configuration

This guide covers the optional SciSiteForge translation path:

- `scripts/translate_site.py`
- the `translation` block in a SciSiteForge site config
- the GenieHive OpenAI-compatible chat endpoint used by the translator

The translator is intentionally separate from the static build path. It does
not own the translation model or routing policy. It reads site config, loads
optional glossaries, and sends paragraph-sized requests to GenieHive.

## Client-Side Configuration

SciSiteForge reads translation settings from the `translation` object in the
site config:

```json
{
  "translation": {
    "provider": "geniehive",
    "base_url": "http://172.24.50.65:8800",
    "model": "scientific_translator",
    "api_key": "change-me-client-key",
    "timeout": 120,
    "system_prompt": "You are a careful scientific translator. Preserve meaning, structure, and technical terms. Return only the translation."
  }
}
```

Recommended meaning of the fields:

- `base_url`: GenieHive control-plane URL or a reverse-proxied client URL. For the TalkOrigins proof-of-concept from `bwng.us`, use `http://172.24.50.65:8800`.
- `provider`: translation backend. The supported provider is currently
  `geniehive`.
- `model`: a GenieHive role ID or directly addressable model name.
- `api_key`: the GenieHive client key, sent as the `X-Api-Key` request header.
- `timeout`: request timeout in seconds.
- `system_prompt`: the translation policy for the client.

The CLI also accepts overrides:

- `--base-url`
- `--model`
- `--api-key`
- `--timeout`

Those flags override the site config for a single run.

## Request Shape

`scripts/translate_site.py` sends GenieHive a standard chat-completions request:

- `POST /v1/chat/completions`
- `model`: from the translation config
- `messages`: one system message plus one user prompt
- `temperature`: low, so translations stay stable

The user prompt asks for:

- translation into the target language
- no commentary
- preservation of structure and technical terminology

## Glossaries

If `scripts/glossary_<lang>.json` exists, the translator loads it and passes
the glossary entries into the prompt.

Use glossaries for:

- fixed technical terms
- proper names that should not be translated
- site-specific terminology

Keep each glossary small and explicit. The translator is not a terminology
database.

## Practical Workflow

1. Set the SciSiteForge `translation` block.
2. Confirm GenieHive is reachable at the configured `base_url`.
3. Confirm the selected GenieHive model or role exists.
4. Run `scripts/translate_site.py`.
5. Review the translated tree before publishing it.

For site-specific translation runs, keep the source tree and destination tree
separate. Translation should not overwrite the English source.

## Suggested Defaults

For local development:

- `base_url`: `http://127.0.0.1:8800`
- `model`: a translation-focused GenieHive role
- `timeout`: `120`

For the current ZeroTier-backed TalkOrigins proof-of-concept:

- `base_url`: `http://172.24.50.65:8800`
- `model`: `scientific_translator`
- `api_key`: `change-me-client-key`

For production or a LAN host:

- use the reverse-proxied GenieHive URL
- keep the API key required
- prefer a translation role with conservative prompt policy

## Relationship to Site Themes

Theme choice and translation are independent.

- themes control layout, styling, and rendering
- translation controls content generation for alternate language trees

Use the same translation setup across `evo-edu`, `talkorigins-modern`, and
`pandasthumb` unless a site has language-specific terminology that needs a
custom glossary or prompt.

For the TalkOrigins modernization proof-of-concept, keep the language switcher
in priority order rather than alphabetical order. A practical top-ten ordering
is:

1. Spanish
2. French
3. Portuguese
4. German
5. Italian
6. Russian
7. Chinese
8. Japanese
9. Arabic
10. Hindi

That order keeps the most broadly useful and generally stable translations near
the top of the chooser while still exposing the full target set.

Use the `coverage` flag on each language entry to decide what appears in the
main switcher. Keep the full intended list in `language_policy.planned_languages`
so the site can show the broader roadmap without advertising unfinished locales
as active.