Heratio Help Center article. Category: AI & Automation.

Translation Management

User Guide

Translate archival descriptions between languages using offline machine translation (NLLB-200). Supports all 11 South African official languages plus major international languages.

Overview

What Gets Translated

• TRANSLATABLE FIELDS
• Title Scope and Content
• Alternate Title Archival History
• Acquisition Arrangement
• Access Conditions Reproduction Conditions
• Finding Aids Related Units of Description
• Appraisal Accruals
• Physical Characteristics Location of Originals
• Location of Copies Extent and Medium
• Sources Rules
• Revision History Edition

Supported Languages

South African Languages

International Languages

How to Access

Step-by-Step Translation

Step 1: Open the Translation Modal

1. Navigate to any archival description record
2. Look for the Translate button/link in the actions panel
3. Click to open the translation modal

Step 2: Configure Translation Settings

Step 3: Select Fields to Translate

• Fields to Translate [Select All] [Deselect All]
• Title [x] Scope and Content
• Alternate Title [ ] Archival History
• Acquisition [ ] Arrangement
• Access Conditions [ ] Reproduction Conditions
• Finding Aids [ ] Related Units
• Appraisal [ ] Accruals
• Physical Characteristics [ ] Location of Originals

Step 4: Preview Translations

Click Translate to generate translations:

Step 5: Review and Edit

• Review each translation for accuracy
• Edit directly in the text area if corrections are needed
• The AI translation is a starting point, not the final word

Step 6: Approve and Save

Click Approve & Save to apply translations:

• SUCCESS
• Successfully saved 2 translation(s) with culture code "en"
• Page will reload automatically...

Translation Options Explained

Save with AtoM Culture Code

• CULTURE CODE OPTION
• ENABLED (Recommended):
• Translation saved to target language culture
• Example: Afrikaans -> English saves to 'en' culture
• Result: Record has separate language versions
• DISABLED:
• Translation saved to source language culture
• Example: Afrikaans -> English saves to 'af' culture
• Result: Original text is replaced

Overwrite Existing

• OVERWRITE OPTION
• ENABLED:
• Replace existing content in target field
• Use when updating/correcting translations
• DISABLED (Default):
• Skip fields that already have content
• Prevents accidental overwrites

Draft System

Translations are saved as drafts before being applied:

• DRAFT WORKFLOW
• 1. Translate --> Draft Created (status: draft)
• 2. Edit --> Draft Updated (if needed)
• 3. Approve --> Draft Applied (status: applied)
• Text saved to record
• 4. Reject --> Draft Rejected (status: rejected)
• No changes to record

Benefits of Draft System

• Preview before committing changes
• Edit translations before saving
• Maintain audit trail of translation history
• Deduplicate identical translation requests

Settings Configuration

Access settings at /translation/settings:

• TRANSLATION SETTINGS
• MT Endpoint:
• [https://ai.theahg.co.za/ai/v1/translate ]
• Example: https://ai.theahg.co.za/ai/v1/translate (the AI gateway; never a node address)
• Timeout (seconds):
• [60 ]
• [Save]

• Health check: /translation/health

Health Check

Test the translation service connectivity:

1. Go to /translation/health
2. Response indicates service status:

{
  "ok": true,
  "endpoint": "https://ai.theahg.co.za/ai/v1/translate",
  "http_status": 200,
  "curl_error": null
}

Common Use Cases

• USE TRANSLATION TO:
• Translate Afrikaans archival descriptions to English
• Create multilingual access to historical records
• Translate Dutch colonial documents for wider access
• Support South African indigenous language preservation
• Enable international researchers to access local archives
• Provide English summaries of foreign language materials

Tips

Troubleshooting

Translation Quality Notes

NLLB-200 (No Language Left Behind) provides good quality for:

• High-resource language pairs (English, French, German)
• Common South African languages (Afrikaans, isiZulu)

Quality may vary for:

• Low-resource language pairs
• Technical/archival terminology
• Historical language forms

Always review translations before applying.

MzansiLM for South African languages

The general-purpose model (qwen3) carries very little African-language training data and produces Dutch-flavoured or hallucinated text for the SA languages. When the operator enables MzansiLM in AI Services settings (mzansilm_enabled plus a mzansilm_endpoint), translation into the routed locales - by default isiZulu, isiXhosa, Sepedi, Sesotho, SiSwati, Xitsonga, Setswana, Tshivenda, isiNdebele and Northern Ndebele - is sent to MzansiLM-125M, a model purpose-trained on the SA languages. If MzansiLM is not configured for a locale, or a call fails, the translation falls back to the default machine-translation / LLM path. Afrikaans is deliberately not routed - the Afrikaans catalogue is operator-maintained.

Need Help?

Contact your system administrator if you experience issues with the translation service.

May 2026 update - UI string storage moved from JSON to DB

Affects: how __()-wrapped UI strings (navbar, browse page, button labels, etc.) are stored, NOT record-content translation. Record-content translation continues to flow through the existing /admin/translation/translate/{slug} workflow.

What changed (issue #57)

UI strings used to live entirely in lang/{locale}.json files on disk. Editing required SSH access. As of v1.52.49 they live in a new ui_string DB table (key + culture + value, one row per pair). The lang/*.json files are now the cold-start fallback only - present on disk but consulted only when a key is missing in the DB.

Migration

One-shot artisan command:

php artisan ahg:translation:import-json-to-db

Walks every lang/*.json and seeds the table. Idempotent on rerun. Initial seed populates ~55,000 rows across 64 cultures.

What this enables

• Per-culture audit and diff are now a single SELECT against ui_string instead of git log over a 7000-key JSON.
• MT-translated values stop polluting git - the DB has its own audit table (ui_string_edit_log).
• Deploy story collapses - one mysqldump instead of a filesystem volume mount of lang/.

Coming next: in-app editor (issue #54, in flight)

A form-based editor at /admin/translation/strings will let admins fix UI strings through a grid (key + per-locale columns + inline edit + AJAX save) instead of SSH-editing JSON. Filters: ?missing=zu (only keys missing in the given locale), ?contains=cart (substring search), ?changed=since:YYYY-MM-DD (recent edits via the audit table).

The MT-suggest button per cell (auto-fill from the existing NLLB endpoint) is gated behind the Server-78 GPU rollout (issue #45).

Part of the Heratio platform