Mehrsprachige Vorlagen

docs101-Vorlagen unterstützen mehrere Sprachen durch ein JSON-basiertes Übersetzungssystem. Dieser Leitfaden erklärt, wie Sie Übersetzungsschlüssel definieren, in Ihren Vorlagen verwenden und mehrsprachige Rechnungen testen.

So funktioniert das Übersetzungssystem

Das Übersetzungssystem folgt vier Schritten:

Übersetzungen definieren: In der Registerkarte Übersetzungen der Vorlage Textschlüssel mit deren Übersetzungen für jede unterstützte Sprache als JSON-Objekt definieren
Schlüssel im Vorlagencode verwenden: Übersetzungsschlüssel im HTML mit {{ t('schlüssel_name') }} referenzieren
Automatische Sprachauswahl: Bei der Rechnungserstellung wählt docs101 die korrekte Sprache basierend auf der Spracheinstellung des Kunden (Englisch oder Deutsch)
Fallback: Wenn ein Übersetzungsschlüssel für die Sprache des Kunden fehlt, greift das System auf die verfügbaren Übersetzungen zurück

Datenstruktur der Übersetzungen

Übersetzungen werden als JSON-Objekt in der Vorlage gespeichert. Die Schlüssel auf oberster Ebene sind Sprachcodes (en, de), und jeder enthält eine flache Schlüssel-Wert-Zuordnung:

{
  "en": {
    "invoice_title": "Invoice",
    "invoice_number": "Invoice #:",
    "date_label": "Date:",
    "due_date_label": "Due:",
    "bill_to": "Bill To",
    "col_description": "Description",
    "col_quantity": "Qty",
    "col_unit_price": "Unit Price",
    "col_total": "Total",
    "subtotal": "Subtotal",
    "vat_label": "VAT",
    "total": "Total Amount",
    "payment_terms": "Payment Terms",
    "thank_you": "Thank you for your business!"
  },
  "de": {
    "invoice_title": "Rechnung",
    "invoice_number": "Rechnungsnummer:",
    "date_label": "Datum:",
    "due_date_label": "Fällig:",
    "bill_to": "Rechnungsempfänger",
    "col_description": "Beschreibung",
    "col_quantity": "Menge",
    "col_unit_price": "Einzelpreis",
    "col_total": "Summe",
    "subtotal": "Zwischensumme",
    "vat_label": "USt.",
    "total": "Gesamtsumme",
    "payment_terms": "Zahlungsbedingungen",
    "thank_you": "Vielen Dank für Ihr Geschäft!"
  }
}

Übersetzungen in der Template IDE bearbeiten

Öffnen Sie eine beliebige Vorlage in der Template IDE und klicken Sie auf die Registerkarte Übersetzungen:

Die Registerkarte Übersetzungen zeigt das aktuelle Übersetzungs-JSON
Bearbeiten Sie das JSON direkt, um Übersetzungsschlüssel hinzuzufügen, zu ändern oder zu entfernen
Stellen Sie sicher, dass jeder Sprachabschnitt (en, de) denselben Satz von Schlüsseln enthält
Klicken Sie auf Speichern, um Ihre Änderungen zu speichern

Schlüssel konsistent halten

Definieren Sie immer denselben Satz von Schlüsseln in jedem Sprachabschnitt. Wenn Sie einen neuen Schlüssel zu en hinzufügen, fügen Sie ihn sofort auch zu de hinzu — und umgekehrt. Dies verhindert fehlende Übersetzungen in generierten Dokumenten.

Übersetzungen in Vorlagen verwenden

Die t()-Funktion

Referenzieren Sie jeden Übersetzungsschlüssel im HTML Ihrer Vorlage mit der t()-Funktion:

{{ t('invoice_title') }}
{{ t('thank_you') }}
{{ t('payment_terms') }}

Bei der PDF-Erstellung gibt t('invoice_title') für englischsprachige Kunden "Invoice" und für deutschsprachige Kunden "Rechnung" aus.

Beispiel: Rechnungskopfzeile übersetzen

Übersetzungs-JSON (Auszug):

{
  "en": { "invoice_title": "Invoice", "invoice_number": "Invoice #:" },
  "de": { "invoice_title": "Rechnung", "invoice_number": "Rechnungsnummer:" }
}

Kopfzeilen-HTML:

<h1>{{ t('invoice_title') }}</h1>
<p>{{ t('invoice_number') }} {{ invoice.invoice_number }}</p>

Ergebnis für einen englischen Kunden: Invoice / Invoice #: INV-2024-001 Ergebnis für einen deutschen Kunden: Rechnung / Rechnungsnummer: INV-2024-001

Beispiel: Tabellenspaltenüberschriften übersetzen

Übersetzungs-JSON (Auszug):

{
  "en": { "col_description": "Description", "col_quantity": "Qty", "col_unit_price": "Unit Price", "col_total": "Total" },
  "de": { "col_description": "Beschreibung", "col_quantity": "Menge", "col_unit_price": "Einzelpreis", "col_total": "Summe" }
}

Rechnungsinhalt-HTML:

<table class="invoice-items">
  <thead>
    <tr>
      <th>{{ t('col_description') }}</th>
      <th>{{ t('col_quantity') }}</th>
      <th>{{ t('col_unit_price') }}</th>
      <th>{{ t('col_total') }}</th>
    </tr>
  </thead>
  <tbody>
    {% for position in positions %}
    <tr>
      <td>{{ position.title }}</td>
      <td>{{ position.quantity }}</td>
      <td>{{ position.unit_price }}</td>
      <td>{{ position.total }}</td>
    </tr>
    {% endfor %}
  </tbody>
</table>

Beispiel: Fußzeilentext übersetzen

Übersetzungs-JSON (Auszug):

{
  "en": { "bank_details": "Bank Details", "terms_notice": "Terms and conditions apply" },
  "de": { "bank_details": "Bankdaten", "terms_notice": "Allgemeine Geschäftsbedingungen gelten" }
}

Fußzeilen-HTML:

<div class="invoice-footer">
  <h3>{{ t('bank_details') }}</h3>
  <p>{{ bank_account.bank_name }} - IBAN: {{ bank_account.iban }}</p>
  <p class="small-text">{{ t('terms_notice') }}</p>
</div>

So funktioniert die Sprachauswahl

Spracheinstellung des Kunden

Jeder Kunde in docs101 hat eine Spracheinstellung (z.B. "English" oder "German"). Bei der Erstellung einer Rechnung oder eines Kontoauszugs:

docs101 liest die Spracheinstellung des Kunden
Ordnet sie einem Sprachcode zu (English -> en, German -> de)
Lädt die entsprechenden Übersetzungsschlüssel aus dem Übersetzungs-JSON der Vorlage
Die t()-Funktion in der Vorlage löst sich in die korrekten Sprachwerte auf

Sprache eines Kunden festlegen

Gehen Sie zum Bereich Kunden
Bearbeiten Sie den Kunden
Setzen Sie das Feld Sprache auf Englisch oder Deutsch
Speichern Sie die Änderungen

Alle zukünftigen Rechnungen für diesen Kunden werden in der ausgewählten Sprache erstellt.

Vorschausprache

Die Vorschau in der Template IDE lädt standardmäßig die englischen (en) Übersetzungen. Um zu sehen, wie Ihre Vorlage auf Deutsch aussieht, erstellen Sie eine Testrechnung für einen Kunden, dessen Sprache auf Deutsch eingestellt ist.

Best Practices für Übersetzungsschlüssel

Namenskonventionen

Verwenden Sie Kleinbuchstaben mit Unterstrichen: invoice_title, col_description, payment_terms
Seien Sie beschreibend: invoice_number_label ist klarer als num
Verwenden Sie Präfixe zur Gruppierung: col_ für Tabellenspalten, payment_ für zahlungsbezogene Texte
Halten Sie Namen kurz, aber aussagekräftig

Inhaltliche Richtlinien

Alles übersetzen: Aller benutzersichtbare Text in der Vorlage sollte t() verwenden — kodieren Sie keinen Text in einer bestimmten Sprache fest
Übersetzungen kurz halten: Längerer Text in einer Sprache kann Layouts sprengen, besonders in schmalen Tabellenspalten. Deutscher Text ist oft länger als die englische Entsprechung, daher sollten Sie beide testen
Konsistent sein: Verwenden Sie durchgehend denselben Begriff (z.B. immer "Rechnung" statt manchmal "Beleg")

Auswirkung auf das Layout

Deutsche Übersetzungen sind typischerweise 20-30% länger als englische. Testen Sie Ihre Vorlage mit deutschem Text, um sicherzustellen, dass Tabellen und Beschriftungen nicht überlaufen oder das Layout brechen.