Locale-correct quotes, dashes, ellipses, apostrophes, symbols and no-break spaces —
one portable spec, designed for byte-identical output across runtimes.
Try it live, no install: polytypo.dev
This is the PHP implementation. The full spec — all locales, all rules, worked examples in each —
lives in polytypo/polytypo. This runtime supports the
text, html and yaml modes fully. markdown mode is not implemented for either dialect
in this runtime (see Markdown mode).
composer require polytypo/polytypouse Polytypo\Polytypo;
Polytypo::transform('She said, "it\'s fine" -- but I wasn\'t sure...', 'en-US');
// => "She said, “it’s fine”—but I wasn’t sure…"Same input, one locale changed — quotes, dash spacing and all follow the target locale, not a single hardcoded style:
Polytypo::transform('Sie sagte: "Alles gut" -- aber ich war mir nicht sicher...', 'de-DE');
// => "Sie sagte: „Alles gut“ – aber ich war mir nicht sicher…"HTML is a first-class mode, not an afterthought — tags, attributes and skip-listed elements
(code, pre, script, ...) are left alone; only text content is touched:
Polytypo::transform('<a title="test... wait">Wait... she said "go on."</a>', 'en-US', mode: 'html');
// => "<a title=\"test... wait\">Wait… she said “go on.”</a>"html mode leaves ten elements alone, with everything inside them: code, pre, kbd, samp,
var, script, style, textarea, svg and math. If you walk a document with a parser of your
own, read Polytypo::SKIPPED_ELEMENTS instead of copying the names; it is a constant array.
$locale has no default anywhere and must always be passed explicitly — there is no silent
fallback to English. $mode defaults to "text" if omitted. Every parameter after $locale
accepts PHP named arguments:
Polytypo::transform($input, 'fr', mode: 'html', rules: ['ranges' => true]);ranges and quote-punctuation are off by default. quote-punctuation moves a comma or full stop
from after a closing quotation mark to before it, in en-US only; every other locale leaves
punctuation where it was typed:
Polytypo::transform('She said "hello", then left.', 'en-US', rules: ['quote-punctuation' => true]);
// => "She said “hello,” then left."yaml mode is the one that asks something of you, and it asks for a reason. YAML is a data format
with prose in some of it, so you name the keys whose values are prose; there is no default and no
guess:
Polytypo::transform(
"summary: Rates -- all of them...\nrun: git diff -- a--b\n",
'en-US',
mode: 'yaml',
keys: ['summary'],
);
// => "summary: Rates—all of them…\nrun: git diff -- a--b\n"Nothing in YAML's syntax separates a sentence from a shell script: description holds one and
run holds the other, spelled identically. Quoting, indentation, anchors and a block scalar's
chomping indicator are never decoded and rewritten — the file is located, not re-emitted — so the
trailing newlines of a |+ block come back exactly as you wrote them. An empty keys array is
legal and processes nothing.
yaml is also the one mode this runtime could implement without a parser, and that is not a
coincidence: symfony/yaml reports no source positions at all, so there was never a parser to
delegate to. The scan is specified in the spec (modes.md §3.8) and written here by hand, the
same way every rule is.
Polytypo::analyze runs the same pipeline and reports what it would do instead of doing it — one
Polytypo\Change per edit, each with the rule that made it and code-point offsets into the input
you passed (into the document, in html and yaml mode, not into a span):
Polytypo::analyze('Wait... "really"?', 'en-US');
// => [ Change { ruleId: "ellipsis", start: 4, end: 7, before: "...", after: "…" },
// Change { ruleId: "quotes", start: 8, end: 9, before: "\"", after: "“" }, ... ]Offsets are code points, not bytes: in 😀 and "this" the opening quotation mark is reported at
6, where strpos would say 9. It is a report, not a patch. The list is empty exactly when
Polytypo::transform would return the input unchanged, and every ruleId is a rule that was
enabled for that call — but two rules may touch the same original range (French spaces deletes
the space before : and nbsp puts a no-break one back), so replaying the list is not guaranteed
to reproduce the output. Call Polytypo::transform for the text. Full contract:
spec/rules/analyze.md.
protect is for text mode when the string has holes that no mode knows about: a ${…} in a
template literal, an ICU argument, a Django or Handlebars tag. It takes a list of
['start' => int, 'end' => int] ranges of the input, half-open, ascending and non-overlapping,
and those code points come back exactly as written while the rules read each one as opaque
content between the text on either side:
Polytypo::transform('${x} - Rules', 'en-US', protect: [['start' => 0, 'end' => 4]]);
// => "${x}—Rules"
Polytypo::transform('${x} - Rules', 'en-GB', protect: [['start' => 0, 'end' => 4]]);
// => "${x} – Rules"Offsets are code points, not bytes, so an emoji before a hole counts as one. Anything else —
a value that is not a list of such ranges, an empty or reversed range, an overlap, a range past
the end of the input, or a non-empty list in html or yaml mode — raises PolytypoException with
POLYTYPO_INVALID_OPTION; null and [] are the same call as leaving the option out. Edits
before a range move it, so a second pass over the output needs the ranges re-located in that
output. Polytypo::analyze accepts protect with the same validation, and no reported range
reaches into a protected run. Full contract: spec/rules/modes.md §3.9.
Every error Polytypo::transform raises is a Polytypo\PolytypoException carrying one of seven
stable codes — check getErrorCode(), not the message text, which is English and informative but
not part of the contract:
try {
Polytypo::transform('x', 'xx-ZZ');
} catch (\Polytypo\PolytypoException $e) {
$e->getErrorCode(); // => "POLYTYPO_UNKNOWN_LOCALE"
}markdown mode requires a dialect, exactly as the spec requires (no default, detection is
forbidden) — but no dialect is implemented by this runtime, so mode: "markdown" always
raises PolytypoException with POLYTYPO_INVALID_DIALECT, whatever dialect value is given.
This is a real gap, not an oversight: league/commonmark (the standard PHP CommonMark/GFM
library) gives no position data at all on inline text nodes — only a line number on block nodes —
so it cannot support the raw-extent span reconstruction this mode requires, and no other
maintained PHP CommonMark/GFM library with that property was found. See
spec/CONFORMANCE.md in the
canonical repository for the exact, current claim.
Polytypo::transform is a pure static method with no static mutable state beyond
memoized-once, never-mutated spec data: safe to call from any context with no external
synchronization.
MIT. See LICENSE.