Translate Like a Pro | Filenames & File Downloads

A downloadable file has two identities at once: what the user sees and what the system stores or delivers. Localization can improve the visible filename, download label and description, but it must not silently change the file type, corrupt an extension, create path characters, break an attachment header or make two different files appear to be the same thing.

Searches for filename localization, Content-Disposition filename, internationalized filenames, UTF-8 filename download, translate filenames, localized file downloads, filename* and HTTP filename encoding point to a technical boundary between language and transport. RFC 6266 defines Content-Disposition behavior for HTTP responses, while RFC 8187 defines UTF-8 based encoding for internationalized HTTP header parameters.

This guide explains how to localize download experiences without confusing a friendly display name with a canonical file identity. It covers visible download text, stored filenames, extensions, MIME types, Content-Disposition, filename and filename*, UTF-8, legacy fallbacks, reserved characters, duplicate names, archives, generated reports, user-uploaded files, screen-reader labels, security, logging and final cross-browser download QA.

This article is part of eduKateSG’s Master Art of Translation architecture. It extends the professional localization layer without replacing the existing owners for file preparation, Unicode, software localization, permission flows or general quality assurance.

Quick answer

Keep file identity, type and delivery metadata separate from the localized label. If the server controls the downloaded filename, generate a safe locale-specific filename while preserving the correct extension and machine references. For HTTP Content-Disposition, use standards-compliant filename handling, including filename* with UTF-8 where appropriate, and test actual downloads across supported browsers and operating systems.

Identify: decide which name is canonical, stored, generated and user-visible.
Protect: preserve extensions, MIME types, IDs and storage keys.
Localize: adapt the human filename only when the product benefits.
Encode: use standards-compliant HTTP header handling.
Sanitize: prevent path separators, control characters and unsafe reserved names.
Disambiguate: avoid collisions between translated filenames.
Test: download on real browsers, operating systems and locales.

1. Separate display name from storage key

A friendly localized filename does not need to be the object’s primary storage identifier. Stable machine keys make caching, permissions, links and deduplication safer.

Professional method. Store files under stable IDs or controlled source names and generate a presentation filename for download when required. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Renaming the target filename also changes the object key and breaks existing references. report_8f37.pdf can remain the object key while the user receives a localized annual-report filename.

Verification. Switch locale and confirm the underlying object URL or storage ID still resolves to the same file. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

2. Preserve the file extension

Extensions communicate file type to operating systems and users. Translating or dropping .pdf, .csv, .xlsx or .zip can break association and trust.

Professional method. Treat the extension as protected machine syntax and localize only the basename unless product design explicitly says otherwise. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A translator changes .docx into a localized abbreviation. A Japanese report name can precede the unchanged .pdf extension.

Verification. Open the downloaded file using the intended application. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

3. Keep MIME type independent from filename

HTTP content type and filename are related but distinct. A familiar extension does not prove the payload type.

Professional method. Send the correct Content-Type from the actual resource and use the filename only for presentation and saving. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. The server sends an Excel MIME type because the localized name ends in .xlsx while the content is really CSV. A generated report can display a localized .csv name while the response explicitly identifies text/csv.

Verification. Inspect response headers and open the saved file. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

4. Understand Content-Disposition

Content-Disposition can instruct a browser to present a response as an attachment and can supply filename parameters. Download behavior and user-visible naming may depend on these headers.

Professional method. Generate the header server-side under a tested library rather than concatenating untrusted user strings. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A localized filename with quotes or control characters corrupts the HTTP header. attachment; filename=… can trigger save-as naming behavior.

Verification. Inspect the network response and actual saved filename. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

5. Use filename* for internationalized names

RFC 6266 supports filename* using the extended encoding mechanism, and RFC 8187 requires UTF-8 for extended parameter values. Ordinary filename parameters are not a reliable universal place for non-ASCII text.

Professional method. Use a tested implementation that emits filename* correctly and, where compatibility requires, a safe fallback filename alongside it. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Raw non-ASCII bytes are inserted into a legacy filename parameter and decoded differently by user agents. A UTF-8 target-language filename can be percent-encoded in filename* while an ASCII fallback remains available.

Verification. Test non-Latin and accented filenames across the browser matrix. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

6. Do not hand-build percent encoding

Header parameter encoding has exact syntax. Double encoding, malformed escapes and wrong character sets can produce unreadable names.

Professional method. Use standards-aware libraries and unit tests with known international examples. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A percent sign already in a name is interpreted as an escape sequence. RFC 6266 explicitly warns about user-agent differences around percent-like sequences.

Verification. Round-trip a representative set of filenames and compare Unicode code points. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

7. Sanitize path separators and reserved characters

A downloaded filename must not become a path traversal or invalid filesystem path. Slash, backslash, control characters and platform-reserved names can have special meaning.

Professional method. Normalize user-facing names into a safe filename policy while keeping the original title separately if needed. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A translated title contains / and creates unintended directories or is rejected by the OS. A report title ‘Sales / Returns’ may need a safe dash in the filesystem filename.

Verification. Save on Windows, macOS and Linux targets if they are supported. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

8. Protect user-uploaded filenames

A user-supplied filename is data, not automatically translatable text. Changing it can destroy identity or legal traceability.

Professional method. Preserve the uploaded original for audit and use a localized download label separately where needed. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A user uploads 合同.pdf and the system translates the base name into an unrelated English phrase. The interface can say ‘Download contract’ while preserving the actual filename.

Verification. Compare uploaded and later downloaded identity under the product’s documented behavior. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

9. Use safe generated names for reports

Generated files often benefit from localized titles and dates. A human can find them more easily outside the product.

Professional method. Compose the basename from controlled localized terms plus machine-formatted safe date/version tokens. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. The date uses slashes and becomes illegal in a filename. A report can use 2026-09-19 rather than a locale date with / characters.

Verification. Generate files across locales and confirm uniqueness. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

10. Avoid translated-name collisions

Two distinct source names can become the same target filename. Synonyms and shortened forms can collapse identity.

Professional method. Add stable disambiguators such as date, record ID or document type when needed. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Two invoices localize to the same generic ‘Invoice.pdf’ and one overwrites the other. Invoice-10482.pdf and Invoice-10483.pdf preserve human usefulness plus identity.

Verification. Download multiple records to the same folder. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

11. Version files without confusing users

Version labels may be technical, editorial or legal. Translating v2, revision codes or dates inconsistently can obscure which file is newest.

Professional method. Protect stable version tokens and localize explanatory words such as final, draft or revised only under approved policy. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Version 10 sorts before version 2 because the filename scheme is inconsistent. manual-v10-fr.pdf can keep a machine-friendly version while the UI displays a natural localized title.

Verification. Sort a folder of versions and confirm intended order. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

12. Keep archive members recoverable

ZIP or archive downloads contain their own internal filenames. Localizing only the outer archive can leave unusable internal names—or over-localizing can break scripts that expect fixed paths.

Professional method. Decide separately whether archive member paths are machine contracts or human documents. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A translated folder name breaks an import workflow after extraction. A documentation bundle may localize PDFs but preserve config/ and data/ paths.

Verification. Extract and run the intended post-download workflow. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

13. Localize download buttons separately from filenames

The action label and the file’s saved name solve different reader jobs. A button can be natural language even when the filename remains canonical.

Professional method. Translate ‘Download report’ and related descriptions normally, while preserving or generating the file name under file rules. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A canonical machine filename leaks into the button label because it was reused as UI text. The user can click a natural ‘Download attendance report’ button and receive attendance-2026-09.csv.

Verification. Review UI label, accessible name and downloaded file separately. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

14. Include file type and size when it helps the user

Download context can prevent surprises. Users may care whether they are opening a PDF, spreadsheet or large archive.

Professional method. Localize the descriptive text but derive type and size from file metadata. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A translated label says PDF while the actual download is XLSX. Download report — PDF, 2.4 MB can be rendered from metadata.

Verification. Compare label metadata with the response. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

15. Keep accessible names aligned

Screen-reader users need to know what will be downloaded. Generic ‘Download’ repeated many times is ambiguous.

Professional method. Use localized accessible names containing the document purpose or filename context. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Ten icon-only download buttons all announce the same word. Download invoice 10483, PDF gives a clear target.

Verification. Navigate the download list with a screen reader. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

16. Protect logs from locale-only filenames

Operational logs often need stable identifiers. Localized filenames can vary with the user’s language and are poor canonical keys.

Professional method. Log stable file/document IDs plus displayed filename as optional context. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Support searches logs for the French filename while the system recorded the Japanese version. document_id=10483 remains stable across every locale.

Verification. Trace one download from UI to server logs. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

17. Regression-test headers and actual saving behavior

Header correctness is not proven by string inspection alone. Browsers and operating systems handle filenames and fallbacks differently.

Professional method. Add response-header and real-download cases to the localization regression suite. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A unit test passes while Safari or an older client saves a garbled fallback name. Test ASCII, accented Latin, CJK, Arabic and emoji policy cases if supported.

Verification. Compare actual saved names to expected locale policy. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

A repeatable operating sequence

A safe file-download workflow starts with stable object identity, then generates user-friendly names at the presentation boundary.

Classify canonical storage keys, source names and display names.
Protect extensions, MIME types and object IDs.
Define the filename-localization policy per file class.
Generate safe locale-aware basenames.
Emit standards-compliant Content-Disposition headers.
Use filename* and UTF-8 where international filenames are required.
Sanitize filesystem-reserved characters.
Add disambiguators for duplicate names.
Keep download labels and accessible names clear.
Test archives and generated reports separately.
Verify real browser/OS save behavior.
Log stable file IDs for support and audit.

Treat the sequence as a loop. If final testing reveals a defect, trace it to the earliest useful source—data identity, file metadata, OCR confidence, extension manifest, challenge configuration, context, language resource or platform state—and repair that source rather than patching only the visible symptom.

Worked scenarios

1. Japanese report filename becomes garbled

The server inserts raw UTF-8 characters into a legacy filename parameter. The key risk is different user agents decoding the bytes differently.

Use a standards-aware Content-Disposition implementation with filename* and a safe fallback. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

2. Translated invoice names overwrite each other

Every localized invoice becomes Invoice.pdf. The key risk is presentation simplification destroying file identity.

Include a stable invoice number or date in the generated target filename. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

3. User upload name is translated

A customer uploads résumé_final.pdf and later sees a machine-generated translation of the name. The key risk is system altering user-owned identity data.

Preserve the original uploaded filename and localize only surrounding UI. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

4. Download label says PDF but payload is CSV

The file-generation format changed without updating UI copy. The key risk is language metadata diverging from actual file type.

Derive visible format labels from authoritative file metadata and regression-test the response. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

5. Archive path gets localized

A ZIP contains config/defaults.json but the folder is translated. The key risk is post-download automation failing.

Keep machine paths stable and localize only human documents or display manifests. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

6. Filename date contains slashes

A locale date formatter generates 19/09/2026 in the basename. The key risk is filesystem-invalid or path-like characters.

Use a safe canonical filename date format while showing the locale-formatted date in UI text. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

File download and filename localization: twenty professional practice cases

For each case, identify the invariant, the localizable layer, the evidence needed to decide, and the final release test.

1. A PDF title contains a colon

Keep the display title intact but sanitize the saved filename for filesystems that disallow colon. State one reason for the decision and one condition that would make you revisit it. That turns a preference into a transferable professional rule.