Mintlify

Was ist Mintlify?

Mintlify ist eine Dokumentationsplattform, die schöne, anpassbare Dokumentationswebsites erstellt. Sie bietet integrierte Such-, Analyse- und API-Playground-Funktionen, um moderne Entwicklerdokumentation zu erstellen.

Was ist Lingo.dev CLI?

Lingo.dev ist eine KI-gestützte Übersetzungsplattform. Die Lingo.dev CLI liest Quelldateien, sendet übersetzbare Inhalte an Large Language Models und schreibt übersetzte Dateien zurück in Ihr Projekt.

Über diesen Leitfaden

Dieser Leitfaden erklärt, wie man die Lingo.dev CLI in einer Mintlify-Dokumentationswebsite einrichtet. Sie lernen, wie man ein Projekt mit Mintlify aufbaut, eine Übersetzungspipeline konfiguriert und die Ergebnisse betrachtet.

Schritt 1. Einrichten eines Mintlify-Projekts

1. Installieren Sie die Mintlify CLI:

   npm i -g mint
   

2. Klonen Sie die Mintlify-Starter-Vorlage:

   git clone https://github.com/mintlify/starter.git
   

3. Navigieren Sie in das Projektverzeichnis:

   cd starter
   

Schritt 2. Erstellen von Quellinhalten

1. Erstellen Sie ein Verzeichnis zum Speichern der Dokumentation in der Quellsprache:

   mkdir en
   

2. Erstellen Sie eine Datei mit Dokumentationsinhalten (z.B. en/overview.mdx):

   ---
   title: "Introduction"
   description: "Welcome to the new home for your documentation"
   ---
   
   ## Getting started
   
   This documentation is automatically translated by Lingo.dev.
   
   ## Features
   
   Our product includes powerful capabilities for modern development.
   

Schritt 3. Konfigurieren der CLI

Erstellen Sie im Stammverzeichnis des Projekts eine i18n.json-Datei:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "mdx": {
      "include": ["[locale]/*.mdx", "[locale]/*/*.mdx"]
    }
  }
}

Diese Datei definiert:

• die Dateien, die Lingo.dev CLI übersetzen soll
• die Sprachen, zwischen denen übersetzt werden soll

In diesem Fall übersetzt die Konfiguration MDX-Dateien von Englisch nach Spanisch.

Wichtig zu beachten ist:

• [locale] ist ein Platzhalter, der zur Laufzeit ersetzt wird. Er stellt sicher, dass Inhalte von einem Ort (z.B. en/index.mdx) gelesen und an einen anderen Ort (z.B. es/index.mdx) geschrieben werden.
• Lingo.dev CLI unterstützt keine rekursiven Glob-Muster (z.B. **/*.mdx). Sie müssen zusätzliche include-Muster erstellen, um Dateien zu übersetzen, die in verschachtelten Verzeichnissen existieren.

Weitere Informationen finden Sie unter i18n.json-Konfiguration.

Schritt 4. Übersetzen des Inhalts

1. Registrieren Sie sich für ein Lingo.dev-Konto.

2. Melden Sie sich über die CLI bei Lingo.dev an:

   npx lingo.dev@latest login
   

3. Führen Sie die Übersetzungspipeline aus:

   npx lingo.dev@latest run
   

   Die CLI erstellt ein Verzeichnis es/ zur Speicherung der übersetzten Inhalte und eine Datei i18n.lock, um zu verfolgen, was bereits übersetzt wurde (um unnötige Neuübersetzungen zu vermeiden).

Schritt 5. Verwenden der Übersetzungen

1. Fügen Sie in der Datei docs.json eine Eigenschaft languages zum Objekt navigation hinzu:

   {
     "navigation": {
       "languages": []
     }
   }
   

2. Fügen Sie für jede unterstützte Sprache ein separates Objekt zum Array hinzu:

   {
     "navigation": {
       "languages": [
         {
           "language": "en",
           "groups": [
             {
               "group": "Getting started",
               "pages": ["en/overview"]
             }
           ]
         },
         {
           "language": "es",
           "groups": [
             {
               "group": "Getting started",
               "pages": ["es/overview"]
             }
           ]
         }
       ]
     }
   }
   

   Beachten Sie, dass:

   • Sie die gesamte Navigationsstruktur für jede Sprache separat replizieren müssen.
   • Mintlify nur eine Teilmenge der Sprachen unterstützt, die die Lingo.dev CLI unterstützt.

3. Starten Sie den Entwicklungsserver:

   mint dev
   

4. Navigieren Sie zu http://localhost:3000. Sie sollten ein Dropdown-Menü zum Umschalten zwischen den Sprachen sehen.

Bekannte Einschränkungen

• UI-Texte, die in der Datei docs.json definiert sind (z.B. Seitenleisten-Gruppenbeschriftungen, Platzhaltertext für die Suche usw.), werden nicht übersetzt.

Unterstützte Sprachen

Mintlify unterstützt nur einen Teil der Sprachen, die Lingo.dev CLI unterstützt. Die aktuellste Liste finden Sie in der offiziellen Dokumentation.