Markdoc

KI-Übersetzung für Markdoc-Dateien mit Lingo.dev CLI

Was ist Markdoc?

Markdoc ist eine auf Markdown basierende Syntax und Toolchain zur Erstellung individueller Dokumentationswebsites. Es erweitert Markdown mit benutzerdefinierten Tags, Variablen und Attributen, um reichhaltige, interaktive Inhalte zu erstellen.

Zum Beispiel:


---

title: Introduction to Markdoc
description: A comprehensive demonstration of Markdoc features and syntax

---

# Introduction to Markdoc

Welcome to this **Markdoc demonstration** document.

{% callout type="note" %}
This is a sample document demonstrating Markdoc capabilities.
{% /callout %}

## Basic Formatting

- Regular text
- *Italic text*
- **Bold text**

Was ist Lingo.dev CLI?

Lingo.dev CLI ist eine kostenlose, Open-Source-CLI zum Übersetzen von Apps und Inhalten mit KI. Sie wurde entwickelt, um herkömmliche Translation-Management-Software zu ersetzen und sich gleichzeitig in bestehende Pipelines zu integrieren.

Weitere Informationen finden Sie unter Überblick.

Über diesen Leitfaden

Dieser Leitfaden erklärt, wie man Markdoc-Dateien mit Lingo.dev CLI übersetzt.

Sie werden lernen, wie man:

  • Ein Projekt von Grund auf erstellt
  • Eine Übersetzungspipeline konfiguriert
  • Übersetzungen mit KI generiert

Voraussetzungen

Um Lingo.dev CLI zu verwenden, stellen Sie sicher, dass Node.js v18+ installiert ist:

❯ node -v
v22.17.0

Schritt 1. Projekt einrichten

Erstellen Sie in Ihrem Projektverzeichnis eine i18n.json-Datei:

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

Diese Datei definiert das Verhalten der Übersetzungspipeline, einschließlich der Sprachen, zwischen denen übersetzt werden soll, und wo sich die lokalisierbaren Inhalte im Dateisystem befinden.

Weitere Informationen zu den verfügbaren Eigenschaften finden Sie unter i18n.json.

Schritt 2. Quellsprache konfigurieren

Die Quellsprache ist die ursprüngliche Sprache und Region, in der Ihr Inhalt verfasst wurde. Um die Quellsprache zu konfigurieren, setzen Sie die Eigenschaft locale.source in der i18n.json-Datei:

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

Die Quellsprache muss als BCP 47 Sprach-Tag angegeben werden.

Eine vollständige Liste der von Lingo.dev CLI unterstützten Sprachcodes finden Sie unter Unterstützte Sprachcodes.

Schritt 3. Konfigurieren der Zielsprachen

Die Zielsprachen sind die Sprachen und Regionen, in die Sie Ihre Inhalte übersetzen möchten. Um die Zielsprachen zu konfigurieren, setzen Sie die locale.targets-Eigenschaft in der i18n.json-Datei:

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

Schritt 4. Erstellen des Quellinhalts

Falls Sie es noch nicht getan haben, erstellen Sie eine oder mehrere Markdoc-Dateien, die den zu übersetzenden Inhalt enthalten. Diese Dateien müssen sich in einem Pfad befinden, der irgendwo die Quellsprache enthält (z.B. als Verzeichnisname wie en/ oder als Teil des Dateinamens wie messages.en.markdoc).

Schritt 5. Erstellen eines Buckets

  1. Fügen Sie in der i18n.json-Datei ein "markdoc"-Objekt zum buckets-Objekt hinzu:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "markdoc": {}
  }
}

  2. Definieren Sie im "markdoc"-Objekt ein Array mit einem oder mehreren include-Mustern:

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

    Diese Muster definieren, welche Dateien übersetzt werden sollen.

    Die Muster selbst:

    • müssen [locale] als Platzhalter für die konfigurierte Sprache enthalten
    • können auf Dateipfade verweisen (z.B. "[locale]/docs.markdoc")
    • können Sternchen als Platzhalter verwenden (z.B. "[locale]/*.markdoc")

    Rekursive Glob-Muster (z.B. **/*.markdoc) werden nicht unterstützt.

Schritt 6. Konfigurieren eines LLM

Lingo.dev CLI verwendet große Sprachmodelle (LLMs), um Inhalte mit KI zu übersetzen. Um eines dieser Modelle zu nutzen, benötigen Sie einen API-Schlüssel von einem unterstützten Anbieter.

Um so schnell wie möglich loszulegen, empfehlen wir die Verwendung von Lingo.dev Engine — unserer eigenen, gehosteten Plattform, die 10.000 Token kostenlose monatliche Nutzung bietet:

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

  2. Führen Sie den folgenden Befehl aus:

    npx lingo.dev@latest login

    Dies öffnet Ihren Standard-Browser und fordert Sie zur Authentifizierung auf.

  3. Folgen Sie den Anweisungen.

Schritt 7. Generieren der Übersetzungen

Führen Sie im Verzeichnis, das die Datei i18n.json enthält, den folgenden Befehl aus:

npx lingo.dev@latest run

Dieser Befehl:

  1. Liest die i18n.json Datei.
  2. Findet die Dateien, die übersetzt werden müssen.
  3. Extrahiert den übersetzbaren Inhalt aus den Dateien.
  4. Verwendet das konfigurierte LLM, um den extrahierten Inhalt zu übersetzen.
  5. Schreibt den übersetzten Inhalt zurück in das Dateisystem.

Beim ersten Generieren von Übersetzungen wird eine i18n.lock Datei erstellt. Diese Datei verfolgt, welche Inhalte bereits übersetzt wurden, und verhindert unnötige Neuübersetzungen bei nachfolgenden Durchläufen.

Beispiel

en/example.markdoc


---

title: Introduction to Markdoc
description: A comprehensive demonstration of Markdoc features and syntax
author: Documentation Team
version: 1.0

---

# Introduction to Markdoc

Welcome to this **Markdoc demonstration** document. This file showcases various Markdoc features and syntax.

{% callout type="note" %}
This is a sample document demonstrating Markdoc capabilities.
{% /callout %}

## Basic Formatting

Markdoc supports standard Markdown features:

1. Ordered lists
2. Unordered lists
3. Text formatting like *italics* and **bold**

es/example.markdoc


---

title: Introducción a Markdoc
description: Una demostración completa de las características y sintaxis de Markdoc
author: Equipo de Documentación
version: 1.0

---

# Introducción a Markdoc

Bienvenido a este documento de **demostración de Markdoc**. Este archivo muestra varias características y sintaxis de Markdoc.

{% callout type="note" %}
Este es un documento de muestra que demuestra las capacidades de Markdoc.
{% /callout %}

## Formato Básico

Markdoc admite características estándar de Markdown:

1. Listas ordenadas
2. Listas desordenadas
3. Formato de texto como *cursiva* y **negrita**

i18n.json

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

i18n.lock

version: 1
checksums:
  829674e11a9003549b66978e9b9c259a:
    heading-0: e19079d431e6b75a7d74e9c35639ea5a
    paragraph-0: 6757b797fc6d8c5ec5628f2619274e28
    paragraph-1: cc37b30c1aca11f64dc096264761368e
    paragraph-2: 50e2b92b9e711ae7758f8edcc1767102
    paragraph-3: 7bc573b304cf3a3414dd60f85eea4e36
    heading-1: 80779abd23399c676227609057093235
    paragraph-4: dfd87f4dde3d3e12fa6781966432465f
    item-0: ad9b7460be42c194e4771cf5281d5fd0
    item-1: 7d67473952061a571de034013964c5b6
    item-2: 91cffca4db2b901a3a0310ca2ab17ed9
    item-3: 56b97b82cc030c511847d1850af088a0
    item-4: 05dc0a811ee5b04941c826293471367d
    item-5: b1701133f7e62467e354a5fc526ea951
    heading-2: ff6e4ea57280ef5a42ebbe2cf9e3273b
    paragraph-5: 3e11ad608af106c15eed82d0e5d07712
    item-6: 2b1ab56131399aab1842fc3a81dd170e
    item-7: 8aedf70e351d5e5bb41ad66ad5ad18d8
    item-8: 1d0eccad0413a69da0d45c481aa754e9
    paragraph-6: e2a208aa62fd61821848519fa2abc211
    heading-3: 2761eb3f80a7da53d2cd899f33641e98
    paragraph-7: f341db1f3167bd074937f4399c3a1158
    th-0: 58f5f3f37862b6312a2f20ec1a1fd0e8
    th-1: e17686a22ffad04cc7bb70524ed4478b
    td-0: 97813c8ae67d69575fd04e35a88aed0c
    td-1: 117451569b718867c43b26d9ee3c4e8f
    td-2: e801c1eaca53c3aa702b747ed750fdd1
    td-3: ffd3eec5497af36d7b4e4185bad1313a
    td-4: 03d20ebc4966301ceba02199a24e02dc
    td-5: 86d0ae6fea0fbb119722ed3841f8385a
    td-6: 6d26991f040628f6002efa192bebb9c2
    heading-4: c8b45e4d54115ec279a2a6bde4b8a725
    paragraph-8: 933c68ed0598328263d1146641d0ab2c
    fence-0: ffdb698812040ead47e2039dfa22d9d7
    paragraph-9: fe471cd364c38cc79a7638b4a5ffb528
    heading-5: 4cbc75f1ae6830a190eb70628c4e4b54
    paragraph-10: bc6097c6af86133a3972bdb7a5343dd2
    fence-1: 31a1aab989ce9935c98e672182bffbbe
    heading-6: fe53e9de958685ab7c70d0a973c0a146
    paragraph-11: 69f77475eb830f1aa357f45db29f809e
    item-9: 90f2650aad06503472c46ce2612b9bc8
    item-10: a392737d0507463d40d1a8ff7502607c
    item-11: 7ed6e23ffae34636a417daf72b3a5b6b
    item-12: 0f93e7285aafb5c9929b29973f047026
    item-13: 9dacb7c56bc894e4bcad39f41265e3a0
    item-14: 496e1d7de5d7ff53f1af813a2ba46d7f
    item-15: 1bd4ec30282cfc0bdf7d5f3559813a1c
    item-16: 46c9eec1392a8d9f33170569e342bf7b
    heading-7: aa8d69ad456402762aeb915a67cfa698
    paragraph-12: 275eb44389d498dab93e38ed2889e5d9
    paragraph-13: f05f450fffcb17520c441ab9789f40ce
    paragraph-14: 915fe5ce4ded772d7844df222ebd9d3e
    paragraph-15: 3fae115ccac303b7cd908b49b8509217
    heading-8: 2fdf7c243436eba4bd1fe5ebd605ab96
    paragraph-16: fc0f77d45ad1e1764d2793706eb8a049
    paragraph-17: 6b4340d30988a714d34f0df9b3e18889
    paragraph-18: a59d117938ed65f303209da2b23ad35a
    paragraph-19: 28e8b27fb60b305a9caac04d8a92a038
    tagName-0: 0421db688c4d19bb542014733d553a43
    paragraph-20: 83951ea4c30a9b5057ff046e3a0bfc07
    paragraph-21: 8d2152d9e84fff4b3cd98d1fb305be8f
    heading-9: 6fe6489310962f6bc8ad13279106568b
    item-17: 0539fa4e65545d8a334abf6e0aee57ab
    item-18: a41ccc6f28eec377fb19a95b0b6db7a8
    item-19: 45aa24cef8a5d9b037d898917a862563
    paragraph-22: 59bf7b09d603b846c2cdd63cd878f20a
    paragraph-23: 9e30a94d9122095ac52a52ed2a864a26
    paragraph-24: 3b28910e425d79f9fd23ada6d6f33bff
    paragraph-25: 05d9c0fe6c099b1e20ebdb2320a28257
    paragraph-26: 04e7322f2d3ffb2d73ff2f64b71637c8
    paragraph-27: 65ef9814c2d07fd3d54d9f7bee1bba6c
    badge-0: c2d5d8760d96802e1b9a7bac290b1cfc
    paragraph-28: df1f854bcdb047d98a68cd39704a8981
    fm-attr-title: e19079d431e6b75a7d74e9c35639ea5a
    fm-attr-description: 82574f93a40b35a16a4c9fc5c2ab58cf
    fm-attr-author: a51ec27845d1fc7cf13c810f0e2d42ab