Zum Hauptinhalt springen

​
Help Center Localization (EN / DE) - Research & Glossary

Internal working document. Not part of the published navigation. For review before we start translating.

​
1. How localization works in Mintlify

Mintlify supports multiple languages natively via a navigation.languages array in docs.json. Key facts:
  • Config: Wrap the navigation in a languages array. Each entry has a language code (ISO 639-1: en, de) and its own full navigation (our tabs/groups/pages).
  • Language switcher: Adding the languages array makes a language switcher appear automatically in the site header - no extra work.
  • Default language: The first entry is the default, or set "default": true on an entry. We would keep en as default.
  • File structure: Translated pages live in a de/ directory that mirrors the English structure (e.g. de/product/about-genow.mdx). English files can stay at their current paths.
  • No path collisions: The same page path must appear in only one language’s navigation. (English keeps current paths, German gets de/... paths - so no conflict.)
  • docs.json UI labels are NOT auto-translated: Group names, tab names, and footer / navbar / banner must be written per language in docs.json (e.g. group "Getting Started" → "Erste Schritte"). If omitted, German inherits the global config.
  • Images: Language-specific images (e.g. German screenshots) go in a language directory and are referenced with relative paths. Shared screenshots can be reused.

​
Translation options

  1. Manual, in-repo (full control, versioned in Git) - matches how we work today.
  2. Mintlify dashboard AI translation (Settings → Translations) / automations - auto-translates and syncs with the main version. Faster, but less control over terminology (our do-not-translate list below would need enforcing).
  3. Third-party tools (e.g. Lingo.dev, generaltranslation) - CLI-based localization.

​
Open decisions before we start

  • API Reference stays English-only. It is generated from OpenAPI specs and our rules forbid touching /api-reference/. We would simply not add it to the German navigation.
  • Scope: 59 published .mdx articles. Every translated page is ongoing double maintenance - each future edit must be made in both languages. Worth deciding how we keep them in sync (manual vs. dashboard auto-sync).
  • CLAUDE.md currently says “Never translate articles into German.” This rule must be consciously updated before translation work begins.

​
2. Do-not-translate glossary (Genow + third-party terms)

These terms are proper product/feature names and should stay in English inside the German articles. (Surrounding sentences get translated; only the term stays.)

​
Core entities

  • Agent, Agent Hub
  • Knowledge, Knowledge Asset (Asset), Knowledge Source (Source)
  • Personal Space, Personal Asset
  • Connector
  • Credential, Credentials Management
  • Service Connection, Service Account
  • Skill, Skills (and the file name SKILL.md / skill.md)
  • Widget

​
Features & settings

  • Context Engine, Agent Context, Context Enrichment
  • Glossary (as the feature name), glossary description
  • Guardrails
  • Guided Search
  • Quick Actions, Actions
  • Fallbacks
  • External Links
  • Direct URLs
  • Keyword Filtering
  • Sub Task Splitting
  • Deep Research, Deep Research Mode
  • Example Questions
  • Contact Persons
  • Support Button
  • QR Code Access
  • Instructions (the field name)

​
UI areas & navigation

  • Admin Panel, Agent Settings, Platform Settings
  • Chat, Translator, Personal Space
  • Threads, New, Browse all agents
  • Thinking Process
  • Analytics Dashboard, Feedback Dashboard
  • Response modes: Fast, Balanced, Precise

​
Roles & permission strings (keep verbatim)

  • Global Admin, Global User, Agent Admin, Agent User, Feature User, Use Case Creator
  • global.Admin, global.User, useCase.[UseCaseID].Admin, useCase.[UseCaseID].User, feature.[featureName].User, useCase.Creator

​
Technical / agentic

  • LLM, RAG
  • MCP, MCP connectors
  • Workspace (upcoming feature name)
  • skill.md spec

​
Third-party / integration names (always keep)

  • SharePoint, Google Drive, Google Workspace, Jira, Confluence, ServiceNow, SAP, Salesforce
  • Entra ID, Microsoft SSO, Google SAML, Firebase, GCP
  • Gemini, GPT / OpenAI
  • Formats/standards: CSV, XLSX, PDF, DOCX, PPTX, MD/MDX, MSG, XML, JQL, CQL, OpenAPI, SPN

​
3. Borderline terms - decision: keep English

Decided: all borderline terms below stay in English in the German articles (consistent with the do-not-translate list above).
Note: the admin panel UI itself is partly German already (e.g. “Anweisungen”, “Agents zuweisen”). Where a German UI label exists, we may add it once in parentheses for orientation, but the canonical term in the docs stays English.