Lorixen.
DE

Downloads mit Umlauten im Dateinamen: Content-Disposition richtig

Kurz gesagt: Wenn ein Kunde auf Ihrer Website „Angebot_Küche_Größe.pdf“ herunterlädt und auf seinem Rechner „Angebot_Küche_Größe.pdf“ oder nur „download.pdf“ landet, liegt das fast immer am HTTP-Header Content-Disposition. Der Server muss den Dateinamen zweifach mitschicken: einmal als einfache ASCII-Variante im Parameter filename und einmal als UTF-8-kodierte Variante im Parameter filename*. Laut MDN bevorzugen Browser filename*, wenn beide vorhanden sind. Mit dieser kleinen Änderung kommen Umlaute, ß und Leerzeichen so beim Kunden an, wie Sie sie vergeben haben.

Woran Sie das Problem erkennen

Typische Rückmeldungen von Kunden oder aus dem eigenen Team klingen so:

  • Der Dateiname enthält seltsame Zeichen wie „ü“ statt „ü“.
  • Umlaute fehlen ganz oder wurden durch Unterstriche ersetzt.
  • Der Download heißt plötzlich „download“, „file“ oder trägt eine Nummer statt eines Namens.
  • In einem Browser stimmt der Name, in einem anderen nicht.

Betroffen sind meist Dateien, die nicht als feste Datei auf dem Server liegen, sondern erst beim Klick erzeugt oder aus einer Datenbank geholt werden: Angebote, Auftragsbestätigungen, Lieferscheine, Kursunterlagen, Exporte aus dem Kundenportal. Genau dort setzt die Anwendung den Dateinamen selbst, und genau dort fehlt oft die richtige Kodierung.

Was der Header Content-Disposition leistet

Der Header teilt dem Browser zwei Dinge mit. Erstens, ob die Datei angezeigt oder heruntergeladen werden soll. Mit inline zeigt der Browser etwa ein PDF direkt an, mit attachment speichert er es als Datei. Zweitens, unter welchem Namen die Datei gespeichert werden soll.

Ein einfacher Header sieht so aus:

Content-Disposition: attachment; filename="Angebot-1234.pdf"

Das funktioniert zuverlässig, solange der Name nur aus ASCII-Zeichen besteht. Sobald Umlaute, ß oder andere Sonderzeichen dazukommen, wird es heikel. Der klassische Parameter filename war ursprünglich nicht für beliebige Zeichensätze gedacht, und Browser haben solche Namen in der Vergangenheit unterschiedlich interpretiert.

Die Lösung: filename und filename* kombinieren

Für Namen mit Sonderzeichen gibt es den Parameter filename*. Laut MDN verwendet er die Kodierung aus RFC 5987: zuerst der Zeichensatz, dann zwei Apostrophe, dann der prozentkodierte Name. Sind beide Parameter vorhanden, bevorzugen Browser filename*. Das ergibt folgende Kombination:

Content-Disposition: attachment; filename="Angebot-Kueche-Groesse.pdf"; filename*=UTF-8''Angebot-K%C3%BCche-Gr%C3%B6%C3%9Fe.pdf

Die ASCII-Variante dient als Rückfallebene für Programme, die filename* nicht kennen. Dort ersetzen Sie Umlaute sinnvoll, also ä durch ae, ö durch oe, ü durch ue und ß durch ss. Die UTF-8-Variante enthält den echten Namen. Moderne Browser zeigen dann „Angebot-Küche-Größe.pdf“ an.

Wichtig ist die Prozentkodierung: Jedes Zeichen außerhalb eines kleinen sicheren Bereichs wird als Bytefolge in UTF-8 geschrieben, also „ü“ als %C3%BC. Die meisten Programmiersprachen haben dafür eine fertige Funktion zur URL-Kodierung. Prüfen Sie aber, ob diese Leerzeichen als %20 oder als Pluszeichen ausgibt. Für filename* brauchen Sie %20, denn ein Plus würde im Dateinamen als Plus erscheinen.

Zeichen, die Sie vorher bereinigen sollten

Nicht jedes Zeichen gehört in einen Dateinamen, auch wenn es technisch kodierbar wäre. Bereinigen Sie den Namen, bevor Sie den Header bauen:

  • Schrägstriche und Backslashes entfernen, denn sie gelten in vielen Systemen als Ordnertrenner.
  • Anführungszeichen entfernen oder ersetzen, weil sie den Header beschädigen können.
  • Zeilenumbrüche und Steuerzeichen grundsätzlich verwerfen. Sie haben in einem Header nichts verloren und können ihn manipulierbar machen.
  • Doppelpunkte, Sternchen und Fragezeichen vermeiden, weil Windows sie in Dateinamen nicht erlaubt.
  • Sehr lange Namen kürzen, zum Beispiel auf 100 Zeichen, damit nichts abgeschnitten wird.

Besonders wenn Kundendaten in den Dateinamen einfließen, etwa ein Firmen- oder Projektname aus einem Formular, ist diese Bereinigung Pflicht. Sonst kann ein ungewöhnlicher Eintrag den Header verändern.

Ein gutes Schema für Dateinamen

Unabhängig von der Technik lohnt ein einheitliches Schema. Bewährt hat sich die Reihenfolge Dokumentart, Nummer, kurzer Bezug und Datum, etwa „Angebot-2026-118-Badsanierung-2026-11-08.pdf“. So sortieren sich Dateien im Downloadordner sinnvoll, und Kunden finden sie später in ihrer Ablage wieder. Verzichten Sie auf Leerzeichen am Anfang oder Ende und auf mehrere Punkte im Namen, weil manche Programme dann die Dateiendung falsch erkennen.

Achten Sie außerdem darauf, dass der Content-Type zur Datei passt. Ein PDF sollte als application/pdf ausgeliefert werden. Stimmen Name und Typ nicht überein, hängen manche Systeme eine zusätzliche Endung an oder öffnen die Datei mit dem falschen Programm.

Inline oder attachment: was für Ihre Kunden passt

Für Angebote und Rechnungen ist inline oft angenehm: Das PDF öffnet sich direkt im Browser, der Kunde kann es lesen und bei Bedarf speichern. Auch dann zählt der Dateiname, denn beim Speichern schlägt der Browser genau diesen Namen vor. Für Exporte, Archive oder Dateien, die ohnehin weiterverarbeitet werden, passt attachment besser. Sie können beides kombinieren, etwa mit einem Knopf „Ansehen“ und einem Knopf „Herunterladen“.

Der HTML-Link mit dem Attribut download kann ebenfalls einen Namen vorschlagen. Er wirkt laut MDN aber nur bei Adressen derselben Herkunft sowie bei blob- und data-URLs. Kommt die Datei von einem anderen Server, etwa aus einem Cloud-Speicher, entscheidet weiterhin der Header. Verlassen Sie sich deshalb nicht allein auf das Attribut.

Downloads aus Cloud-Speichern

Viele Betriebe legen Dateien nicht mehr auf dem eigenen Webserver ab, sondern in einem Objektspeicher. Dort wird der Header beim Hochladen der Datei als Metadatum gespeichert oder beim Erstellen eines zeitlich begrenzten Download-Links mitgegeben. Kontrollieren Sie, ob Ihr Code dabei denselben kodierten Namen setzt. Ein häufiger Fehler: Die Anwendung baut den Header lokal korrekt, aber beim Umzug in den Cloud-Speicher wird nur noch die Objekt-ID übergeben, und der Kunde bekommt eine Datei mit kryptischem Namen.

So testen Sie die Änderung

Ein Test dauert wenige Minuten:

  1. Erstellen Sie ein Testdokument mit einem Namen, der ä, ö, ü, ß, ein Leerzeichen und einen Bindestrich enthält.
  2. Öffnen Sie die Entwicklerwerkzeuge im Browser, wechseln Sie zum Netzwerk-Tab und lösen Sie den Download aus.
  3. Prüfen Sie im Antwortheader, ob filename und filename* vorhanden und korrekt kodiert sind.
  4. Laden Sie die Datei in mindestens zwei Browsern und auf einem Smartphone herunter und vergleichen Sie die Namen.
  5. Öffnen Sie die gespeicherte Datei, um sicherzugehen, dass Typ und Endung stimmen.

Auf der Kommandozeile zeigt ein Abruf mit curl und der Option für Header den Wert ebenfalls an. So lässt sich der Test auch automatisieren, etwa nach jedem Update der Anwendung.

Beispiel aus der Praxis

Ein Installateurbetrieb in Graz verschickt Angebote über ein Kundenportal. Die Dateien hießen dort nach dem Muster „Angebot_Bäder_Größe“, bei vielen Kunden kamen sie aber mit verstümmelten Zeichen an. Einige Kunden fragten nach, ob die Datei beschädigt sei. Nach der Umstellung schickt das Portal einen ASCII-Namen und einen UTF-8-Namen mit, bereinigt Sonderzeichen und hängt Angebotsnummer und Datum an. Die Rückfragen zu „kaputten“ Dateien sind seither ausgeblieben. Das Beispiel ist illustrativ.

Häufige Fragen

Reicht es, Umlaute einfach ganz zu vermeiden?

Das ist die schnellste Notlösung, wirkt aber unschön, besonders bei Namen und Orten. Mit filename* zeigen Sie den echten Namen, und die ASCII-Variante bleibt als Rückfallebene.

Muss ich bei inline auch einen Dateinamen setzen?

Ja, das empfiehlt sich. Der Browser schlägt diesen Namen vor, wenn der Kunde die angezeigte Datei speichert.

Warum stimmt der Name in einem Browser und im anderen nicht?

Meist fehlt filename*, und die Browser interpretieren die Sonderzeichen im einfachen filename unterschiedlich. Mit beiden Parametern verschwindet der Unterschied in aktuellen Browsern.

Kann ich den Kundennamen in den Dateinamen schreiben?

Das ist möglich, solange Sie ihn vorher bereinigen und kürzen. Steuerzeichen, Anführungszeichen und Schrägstriche dürfen nie ungefiltert in den Header gelangen.

Wenn Ihre Downloads im Kundenportal noch mit verstümmelten Namen ankommen, prüfen wir den Header gerne mit Ihnen: Downloads prüfen lassen.

Quellen

WhatsAppTermin buchen