fontTools pyftsubset helps localization engineers reduce font assets without accidentally deleting the letters, marks and shaping features that real languages need. A small webfont may load faster, but the saving is not worthwhile if Vietnamese accents disappear, Arabic letters stop joining, a Devanagari conjunct breaks or the wrong regional Chinese glyph appears in a multilingual interface. A safe font subset begins with realistic text coverage and ends with testing in the target renderer.
This practical fontTools subset CLI guide explains how to prepare UTF-8 character corpora, use the fonttools subset command or its pyftsubset interface, choose Unicode ranges, preserve OpenType layout behavior, produce WOFF2 files and verify missing characters before shipping translated websites or apps. It also explains why Unicode code point coverage is only one test: ligatures, mark anchors, language-sensitive substitutions, fallback fonts and licensing matter too.
Teams publishing globally should treat font subsetting as a controlled packaging operation, not a translation shortcut. The instructions below are suitable for software documentation, storefronts, user interfaces, educational resources and multilingual publishing. Commands are illustrative and must be tested against the installed fontTools version and licensed font files. A native-language reviewer should approve visible results in the final browser or application.
Quick start: practical decisions before running the subsetter
- Keep the original licensed font untouched, under a distinct filename and version.
- Build a verified text corpus from every language, product feature and content type you support.
- Make the subset operation fail when required characters are absent, rather than quietly omitting them.
- Preserve required shaping features and test demanding text such as combining marks and conjuncts.
- Check the correct output format, font metadata and permitted licensing or embedding rights.
- Test fallback, line wrapping, search and copy-paste in browsers and applications, not only with a font viewer.
What fontTools removes and why it matters
A Unicode font is not simply a bag of letters. Its tables describe which characters map to glyphs, how those glyphs are positioned, how ligatures are formed and how the font identifies itself. A subsetter builds a smaller asset from an initial selection of text, code points or glyphs, then retains the dependent data needed for the chosen behavior. That dependency analysis is valuable, but it cannot predict future customer names or untranslated content that was excluded from the input corpus.
A company might serve English, French and Vietnamese with one Latin-oriented subset, and Arabic or Japanese with other carefully engineered assets. That arrangement can work well if browser fallback and CSS declarations are designed correctly. It can also fail silently when a character falls outside the planned range or when the browser chooses an unexpected family for a combining mark. There is no universally correct size or language partition.
FontTools documents that its subsetter operates on TrueType/OpenType fonts and webfont variants and supports initial glyph sets by text, Unicode lists, glyph names or glyph identifiers. For localization work, text or Unicode selection is often easier to audit than internal glyph numbers because the latter are private to a specific font build. A source corpus is not a substitute for measuring coverage in the published product.
A conservative, reproducible fonttools subset example
python -m pip show fonttools
fonttools subset --help
fonttools subset Original.ttf --text-file=approved-characters.txt --output-file=SiteSubset.woff2 --flavor=woff2 --no-ignore-missing-unicodes
# Inspect the output with the TTFont Python example below.These commands use a placeholder licensed font and a local UTF-8 corpus. WOFF2 output requires relevant Brotli support in the environment. The TTFont Python example below provides a more useful inspection step than an unverified command-line subcommand: it loads the produced font and checks its character map against required source text. That comparison should be followed by actual shaping and rendering tests for each language.
To inspect a font in Python without altering it, the TTFont API can read the cmap and table metadata. In a basic script, load the subset and collect Unicode keys from its best character map; compare the set against the code points in the approved corpus. Then run real shaping and renderer checks. A font can map a code point yet still lack acceptable mark positioning, and a glyph can be preserved but selected incorrectly for a language context.
from fontTools.ttLib import TTFont
font = TTFont("SiteSubset.woff2")
cmap = font.getBestCmap() or {}
required = set(open("approved-characters.txt", encoding="utf-8").read())
missing = sorted(ord(ch) for ch in required if ord(ch) not in cmap)
print("Missing code points:", [f"U+{v:04X}" for v in missing])This Python example is a simple coverage check, not a complete multilingual acceptance test. Newline and control characters may not need corresponding visible glyphs, so in a production test classify required printable characters separately from formatting controls. The exact behavior of Unicode variation selectors, zero-width joiners and fallback faces also needs application-level inspection. Keep code points, display expectations and glyph coverage as related but distinct measurements.
Strict missing-character checks are especially important because the documented default of the subsetter may ignore missing Unicode characters unless you select the option that refuses them. A green terminal exit is meaningful only when it reflects the required coverage contract. Always read the tool’s own warnings and compare the resulting file to the input corpus before calling the font complete.
Designing an auditable font subset project
Create a versioned directory with an original-font inventory, approved language list, UTF-8 corpus, build command, generated assets and QA records. Record the original filename, font version or checksum, file license, output hash, expected Unicode ranges and deployed CSS mappings. Keep business inputs such as product names, shipping addresses and user-generated text separate from static interface strings because their coverage risk differs.
Decide whether the asset will appear only in a fixed set of labels or in open-ended text entry. A very small subset can be sensible for a fixed logo caption but not for a customer-support textbox accepting names from around the world. If user content or future translated documents can introduce new characters, plan broader coverage, fallback fonts or a dynamic font strategy rather than promising one tiny asset will cover everything.
Optimize only after measuring user-visible outcomes. The relevant metrics include total transferred font bytes, repeated downloads across pages, first meaningful text rendering and final layout stability. A smaller file that triggers extra fallback requests, causes a flash of mismatched text or changes line breaks can worsen the user experience. Make build performance and readability joint goals.
Thirty-one real-world font subsetting and translation QA situations
1. English-only tests are a poor multilingual specification
An alphabet sample proves that ordinary Latin letters exist but says nothing about characters introduced by translation, customer names or regulatory documents. Even a page with English headings may include currency signs and punctuation absent from the sample.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Collect messages from real product surfaces and target-language review material. Compare character coverage by locale and keep an exception list for open-ended content.
The approval standard must reflect the actual language and publishing task. Approve only after every supported language has representative prose, numbers and formatting in the accepted corpus. Treat future content as a deliberate policy decision.
2. French, Spanish and Portuguese accents
Western European content uses different diacritics and punctuation from plain English. A subset created from ASCII may display most letters while replacing one accented vowel in a name with a fallback font.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Use natural sentences, punctuation and personal names checked by editors. Run strict missing-Unicode checks and look for unexpected mixed-font rendering.
The approval standard must reflect the actual language and publishing task. Validate on pages where text appears in uppercase, bold, italic and small controls; the required characters should remain legible under all supported styles.
3. Vietnamese complex diacritics
Vietnamese frequently combines distinctive vowel forms with tone marks. A subset that includes one presentation of a letter may still fail when content arrives in a different normalized representation or when mark anchors are damaged.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Include naturally authored Vietnamese text and test both common Unicode representations where the product accepts them. Confirm necessary combining characters and shaping behavior.
The approval standard must reflect the actual language and publishing task. Pass only when accents remain readable and correctly attached at small sizes, and when copied text preserves the original intended characters.
4. Arabic letter joining after reduction
Arabic shaping can select contextual forms and ligatures through OpenType data. A font may contain a basic character mapping while the reduced asset lacks features used for readable Arabic.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Keep relevant layout features and compare the same reviewed words with the original and subset fonts using a shaping tool and application renderer.
The approval standard must reflect the actual language and publishing task. Do not replace Arabic letters with presentation forms to hide a failed subset. Correct the font production process or choose an appropriate font.
5. Arabic combining marks
Vowel marks and other annotations often depend on font positioning tables. Unnecessary stripping of layout data may produce collisions even though every base character is present.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Construct representative fully marked words, preserve their exact code points and inspect rendering at product sizes, including low-resolution screens.
The approval standard must reflect the actual language and publishing task. Mark placement, not only coverage, determines a pass. Check under realistic text color, line height and clipping conditions.
6. Persian and Urdu variant characters
Persian and Urdu use characters that differ from lookalikes in Arabic; Urdu styles may also require different typographic treatment. A generic Arabic subset should not be assumed sufficient.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Create separate corpora for the supported languages with reviewed lexical examples, and keep the exact source code points.
The approval standard must reflect the actual language and publishing task. Native-language approval is required for letter identities and overall readability. An apparently close shape can change user trust or meaning.
7. Devanagari conjuncts and half forms
Indic shaping depends on related characters and layout substitutions. Reducing a font to simple Unicode-mapped glyphs without dependencies can break consonant conjuncts.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Include conjunct-rich Hindi examples, require the expected OpenType shaping data and compare to the original font with the same renderer.
The approval standard must reflect the actual language and publishing task. Validate whole words, not only charts of individual glyphs; disconnected conjuncts are a release failure.
8. Bengali and Assamese differences
Bengali-script content can involve language-specific forms and consonant combinations not represented in an English or Hindi-only test corpus.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Keep locale-specific text and compare how the subset font behaves under the intended application language context.
The approval standard must reflect the actual language and publishing task. Do not merge approval into an ‘all Indic passed’ label. Each supported language deserves evidence from competent readers.
9. Tamil and Malayalam syllable shaping
South Asian scripts differ in conjunct behavior, mark placement and supported font designs. Retaining glyphs for one script is not evidence that another works.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Prepare separate Tamil and Malayalam samples with dependent vowels, clusters and ordinary UI labels before subsetting.
The approval standard must reflect the actual language and publishing task. Verify at real control widths and with natural spelling. Fall back intentionally if one family cannot serve both well.
10. Thai and Lao combining marks
Thai and Lao can stack marks in ways that fail under tight line-height constraints. Their visible marks can be lost through asset errors or clipping in the final interface.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Include mark-rich samples and inspect both font output and actual layout dimensions after reducing the font.
The approval standard must reflect the actual language and publishing task. Check compact menus, mobile text and error notices; a technically present glyph is useless if clipped by the component.
11. Khmer script and stacked glyphs
Khmer shaping involves complex combinations that need more than a list of Unicode characters. A reduced font may lose required glyphs that are selected indirectly.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Test common words and challenging stacked forms using an approved Khmer corpus and compare the original to the subset.
The approval standard must reflect the actual language and publishing task. Ensure syllables remain comprehensible and lines do not overlap; do not rely solely on font byte savings.
12. Myanmar Unicode versus legacy encodings
Some historical text pipelines use incompatible legacy representations. A new Unicode webfont subset cannot repair a source corpus stored in the wrong encoding.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Validate text source and Unicode representation before collecting code points. Keep legacy-data remediation distinct from font production.
The approval standard must reflect the actual language and publishing task. A successful release renders correct modern Unicode text and does not silently substitute visually similar but invalid sequences.
13. Hebrew pointed text and cantillation
Unpointed Hebrew letters may pass while pointed or annotated text fails because required marks or positioning support are absent.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Include authentic pointed examples where needed by the product, and preserve their combining characters and anchor-related layout data.
The approval standard must reflect the actual language and publishing task. Review full sentences at usable sizes, especially in educational or religious contexts where small marks carry important meaning.
14. Chinese character range planning
Chinese text uses many characters, making simplistic all-or-nothing subsets expensive or incomplete. Frequent interface strings and open-ended articles have different coverage requirements.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Analyze the exact publishing corpus and plan language-specific assets, multiple ranges or reliable fallbacks. Keep broader fonts available for user-generated text.
The approval standard must reflect the actual language and publishing task. Document coverage limits transparently. Never claim universal Chinese support from a handful of common UI words.
15. Traditional and Simplified Chinese
Some strings share Unicode characters, while others differ; even shared characters can have regional glyph preferences. Text conversion and font selection are separate tasks.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Prepare independently reviewed Simplified and Traditional corpora, including regional language requirements and font expectations.
The approval standard must reflect the actual language and publishing task. A valid subset preserves the intended character identities, shapes and layout features without conflating orthographic conversion with asset compression.
16. Japanese kanji and kana
Japanese combines kanji, hiragana, katakana and punctuation. A corpus based solely on common kana leaves scientific terms, names and rarely used kanji outside the font.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Collect actual UI, documentation and user-name examples. Evaluate whether rare characters should use a compatible fallback face.
The approval standard must reflect the actual language and publishing task. Approve visual balance and Japanese typographic conventions as well as basic coverage, particularly in vertical layouts if supported.
17. Korean Hangul syllables and jamo
Korean may include precomposed Hangul syllables as well as jamo sequences. Static English-centric font coverage provides no useful assurance.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Test authentic Korean text plus any decomposed or historic forms the product must support. Compare output using the intended shaping and fallback stack.
The approval standard must reflect the actual language and publishing task. Make acceptance criteria correspond to the actual language scope, rather than demanding irrelevant historic characters or omitting necessary modern syllables.
18. Numbers, decimals and currency
Localized pages may use Arabic-Indic digits, decimal separators, percent signs or monetary symbols that a static word corpus misses.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Include representative totals, dates, invoices, prices and unit expressions from each supported locale without inventing real financial transactions.
The approval standard must reflect the actual language and publishing task. Reject outputs that drop signs or switch fonts unpredictably in critical values. Confirm layout, interpretation and copy behavior together.
19. Mathematical and scientific notation
Educational materials may require Greek letters, arrows, operators, subscripts and symbols outside normal prose. These often appear in callouts or diagrams.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Include real curriculum notation and ensure the designated typeface covers every symbol, or assign a controlled mathematical fallback.
The approval standard must reflect the actual language and publishing task. Review formula spacing and distinctness of characters. A visually similar substitution can be mathematically wrong.
20. Punctuation and quotation styles
Languages use different quote marks, dashes, brackets and spacing conventions. An incomplete font sometimes looks fine until localized punctuation falls back.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Extract punctuation from real content, include language-specific marks and test surrounding line breaks.
The approval standard must reflect the actual language and publishing task. Check narrow screens as well as desktop pages, because stray fallback punctuation can change width and wrapping.
21. Emoji, variation selectors and ZWJ sequences
Emoji presentation involves sequences, selectors and platform color-font behavior. Basic font subsetting may not preserve complex emoji capabilities.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Separate emoji rendering expectations from text glyph coverage, and verify representative user-facing sequences on target platforms.
The approval standard must reflect the actual language and publishing task. Do not promise complete emoji support from a monochrome text subset. Preserve accessible text equivalents where appropriate.
22. Ligatures and required OpenType features
Not every glyph needed at runtime appears as a direct Unicode character. Layout features can select additional glyphs for contextual shaping or ligatures.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Understand the subsetter’s default feature retention and explicitly preserve any optional features the design actually requires.
The approval standard must reflect the actual language and publishing task. Confirm that retained tables work with the final browser or app and test any intentional feature overrides independently.
23. Font metadata and language names
Subsetting can modify name tables or retain only selected language records. That can affect font discovery, licensing notices and desktop workflows.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Review name-IDs and name-languages options when generating assets and inspect important metadata in the output.
The approval standard must reflect the actual language and publishing task. Preserve legally required notices and operationally meaningful identity fields; do not assume invisible metadata is disposable.
24. Font license and embedding restrictions
A technically valid subset is not automatically licensed for redistribution or conversion. Some fonts impose conditions on embedding, modification or naming.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Check the actual license before producing WOFF2, publishing files or bundling the font into an app, and record that check.
The approval standard must reflect the actual language and publishing task. If the rights are uncertain, choose a font with clear redistribution permissions instead of proceeding because the command succeeded.
25. WOFF2 compression dependencies
WOFF2 output may require Brotli dependencies. A missing library is a build-environment problem, not a reason to alter translated text.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Record the fontTools and compression environment and verify the generated output can be read by the target browser.
The approval standard must reflect the actual language and publishing task. Test network delivery, content type and font loading, including fallback behavior when a font asset is blocked.
26. Unicode-range declarations in CSS
A CSS unicode-range controls when the browser considers a webfont relevant. Incorrect ranges can create gaps even if the file itself contains the right characters.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Compare declared ranges against each generated subset and test mixed-language pages with browser network and font inspection tools.
The approval standard must reflect the actual language and publishing task. A passing page loads the expected assets and chooses compatible fonts for text, punctuation and combining marks.
27. Fallback mismatch between subsets
Multiple font files may have different metrics, weights or typographic styles. Switching between them inside one word can look broken and damage mark positioning.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Test entire paragraphs that mix languages, symbols and user names. Inspect which font actually rendered suspicious spans.
The approval standard must reflect the actual language and publishing task. Keep fallback design intentional, with compatible weights and sizes. Do not treat every fallback occurrence as harmless.
28. Variable fonts and axis behavior
A variable font can contain extra variation data beyond the static glyph set. Subsetting should not accidentally discard settings the product uses.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Test actual supported weights and other design axes in the deployed asset, including extreme settings of responsive components.
The approval standard must reflect the actual language and publishing task. Compare to original-font output and require stable readability; output size alone cannot determine which axes are worth retaining.
29. PDF export and copyable text
Webfont success does not guarantee that a document converter or PDF exporter uses the same embedded fonts or encoding maps.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Generate representative PDFs, inspect font embedding and test text extraction, search and copy-paste in the final document.
The approval standard must reflect the actual language and publishing task. Keep real selectable text where the workflow requires it; a rasterized screenshot does not satisfy document accessibility.
30. Dynamic customer names and external content
Translations may pass with a static interface corpus while user-provided names or imported records contain unsupported scripts. The defect often appears late and unpredictably.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Model expected input origins and their language diversity; use a broad fallback or a documented dynamic font policy.
The approval standard must reflect the actual language and publishing task. Never silently discard unsupported characters. A graceful readable fallback protects identity, accessibility and support operations.
31. Pre-release checks and future font updates
A regenerated subset can differ in coverage, layout behavior and internal font metadata after a tool or typeface upgrade.
In a controlled build, preserve the original asset and gather evidence before changing parameters. Pin source versions, build commands and corpus hashes, then compare character coverage and visual fixtures after changes.
The approval standard must reflect the actual language and publishing task. Approve changes through documented tests and a small native-language review rather than assuming deterministic build output equals language quality.
Building a reliable multilingual font release
Begin with a coverage report per supported language, not an anonymous global percentage. If the product has five locales, reviewers should be able to inspect what each locale expects and which actual characters are missing. Include user-generated content policy, regulated terminology, proper names and the shape of localized numerals. Decide explicitly which paths can use fallback and which require direct support in a selected font.
Use stable commands in version-controlled scripts and keep generated fonts out of the source directory. A release engineer should be able to reproduce an asset from its licensed original, corpus and settings. The resulting filenames should identify compatible versions; accidental overwrites make it difficult to prove which site release served a problematic font. Maintain a rollback asset if production monitoring reveals missing glyphs.
Measure savings against an accurate baseline. Compare compressed bytes shipped to a user, the number of font requests and the impact on layout stability, not only the size of an isolated file on disk. A tiny subset used on one page may not improve the experience if every navigation to a different language downloads several more subsets. Consider caching and cross-page reuse before fragmenting a font into many narrow slices.
Automate a printable-character coverage check, but make the report explain any intentionally excluded controls or unsupported locales. Treat warnings about missing Unicode characters as release questions, not background noise. Follow with shaping tests that preserve the correct scripts and optional features, then full application screenshots at relevant sizes. Human judgment is indispensable when a glyph is technically present but looks incorrect or inappropriate for a language.
After launch, collect bug reports with the exact text, locale, browser or app version, device, used font and screenshot where safe. A report saying only ‘some accents are broken’ is hard to reproduce; a report that names a word and affected locale allows engineers to trace corpus gaps, CSS ranges or font table changes. Update the approved corpus after resolving real issues so the same defect cannot recur silently.
Questions users and localization teams often ask
Is pyftsubset different from fonttools subset?
They refer to the fontTools subsetting functionality exposed through command-line interfaces. Packaging and entry point availability can differ by installation; use the documented interface available in your environment and record its version.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.
Can I subset a font from a translated webpage?
You can build a corpus from text you legitimately control, but live pages alone may omit future dynamic content, hidden screens, error messages or user names. Supplement with a documented language coverage policy.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.
Why do required characters disappear even when the command exits successfully?
Check the input corpus, default missing-Unicode behavior, actual font coverage and the generated output. A success return does not necessarily certify every character you hoped to include.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.
Should I always keep every OpenType feature?
Not automatically. Keeping all features can grow the file, while dropping required ones breaks shaping. Preserve features needed by supported scripts and design behavior, then measure and test the output.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.
Does a smaller WOFF2 always improve SEO?
No guaranteed ranking benefit follows from a smaller file. Faster and more stable text rendering can improve user experience, but outcomes depend on delivery, caching, layout and the entire page. Measure real user-facing performance.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.
Can a font subset solve incorrect Chinese translation?
No. It can include required glyphs, but semantic translation and Simplified/Traditional editorial decisions are separate. Use qualified language review and appropriate font variants.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.
How do I handle letters missing from the original font?
A subset cannot create missing artwork or shaping support. Choose a suitable licensed font, introduce a deliberate fallback or redesign the coverage plan.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.
What matters most for Arabic or Indic scripts?
Test complete natural words with required shaping and combining marks. Direct Unicode coverage must be paired with retained OpenType layout behavior and native-reader approval.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.
Can I use one tiny font file for every world language?
Usually that is an unrealistic design goal when scripts, CJK character counts and user-generated content are involved. A layered coverage and fallback strategy is more defensible.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.
What should be archived for audit?
Keep the original font identity and license, build settings, source corpus and its hash, generated file checksum, coverage results, representative visual outputs and approval notes.
When making the decision, refer back to actual users and supported content rather than chasing one universal optimization setting. A measurable rendering improvement is valuable only when text remains correct, accessible and maintainable.