77. Publikovaný obsah může být psán v jazyce čtenáře; vlastní artefakty repozitáře ne
Kontext
project.english-only v1 řekl jednou větou a bez výhrad:
Kód, komentáře, commity, dokumenty a záznamy správy se píší anglicky, bez výjimek.
Je to blokující pravidlo a je zapojeno do scripts/ci/english-only-check, které rozhoduje tu část, kterou umí rozhodnout abeceda: písmeno, které se vyskytuje v češtině, slovenštině nebo polštině a nikdy v angličtině, nebo celé nelatinské písmo, v jakémkoli sledovaném autorském souboru. Strom obsahu webu je v rozsahu. V tomto stromu není žádná baseline dluhu, takže jeden nález kontrolu shodí.
To pravidlo bylo napsáno, když bylo tvrzení o tomto repozitáři vyčerpávajícně pravdivé: každý artefakt v něm byl pracovní artefakt — něco, co přispěvatel nebo agent čte, aby změnil kód. Pro pracovní artefakt je důvod pravidla přesně správný a toto rozhodnutí ho neoslabuje. Komentář v jiném jazyce je druhá kniha pravidel pro toho, kdo ho neumí číst, a na repozitáři pracují lidé a agenti, kteří myslí v jiném jazyce než angličtině, což je přesně důvod, proč kontrola existuje.
Od té doby repozitář získal druhý druh artefaktu, který v1 nikdy nemusela rozlišovat: publikovaný web. site/content-src/ drží stránky psané pro čtenáře, který na tomto repozitáři vůbec nepracuje. Stránka určená českému čtenáři, česky, není druhým pravidlem pro přispěvatele; je to produkt, který mluví ke svému publiku.
Spouštěč byl konkrétní. Dva dlouhé články vznikly z jedné báze důkazů, jeden anglicky a jeden česky — ne překlad, dva nezávisle složené kusy. Anglický šel publikovat. Český ne a žádná ze dvou únikových cest vedle kontroly se nehodila: name je pro vlastní jména, fixture pro soubor, který používá cizí řetězec jako data, a hlavička kontroly sama uvádí, že ani jedno nevyjímá větu. Deklarovat článek jako fixture by bylo zneužití výjimky, jejíž dokumentace přesně to zakazuje, a --write-baseline by jej vyprala na známý dluh. Poctivé možnosti byly změnit pravidlo, nebo nepublikovat.
Rozhodnutí
Vlastní artefakty repozitáře se píší anglicky, bez výjimek. Publikovaný obsah určený čtenáři může být napsán v jazyce tohoto čtenáře, za třech podmínek, z nichž každou rozhoduje kontrola, ne revize.
- Umístění. Žije pod
site/content-src/, autorským zdrojem publikovaného webu, nebo je generovanou projekcí takové stránky podsite/content/. Nikde jinde v repozitáři toto oprávnění nevzniká — anidocs/, ani.ai/, ani v komentáři, ani ve zprávě commitu. - Deklarace. Deklaruje se v
scripts/ci/english-only-allow.txttřetím druhem,translation <path> <language> <why>, který nese jazyk a povinný důvod, ve stejném tvaru jako dva stávající druhy. - Sebedeklarace, kontrolovaná oběma směry. Stránka sama deklaruje svůj jazyk ve front matter (
[extra] lang = "<language>") a kontrola odmítne deklaraci, jejíž jazyk neodpovídá jazyku stránky. Jednostranná deklarace — položka allow-listu, se kterou nic na stránce nesouhlasí — je nález, ne úspěch.
Pravidlo přechází na verzi 2 s rozlišením zapsaným do svého znění. Chování při selhání se pro vše, co není publikovaný obsah, nemění.
Důsledky
Kontrola zůstává přísná tam, kde přísná byla. Vše, co kontrola v1 odmítala, kontrola v2 stále odmítá: českou větu v komentáři .rs, slovenské slovo v pravidle, zprávu commitu v jiném jazyce, český odstavec v docs/. Povolení je omezeno na strom, jehož účelem je publikace, a dále na soubory, které se samy deklarují.
Výjimku nelze získat přidáním do seznamu. Protože stránka musí deklarovat vlastní jazyk a kontrola obojí porovnává, položka přidaná do allow-listu pro umlčení nálezu selže, pokud stránka skutečně není tím, čím položka tvrdí. Je to táž vlastnost, jakou druh fixture získává ze svého povinného důvodu, učiněná rozhodnutelnou místo posuzovatelné.
Web musí přestat tvrdit jeden jazyk pro všechny stránky. site/templates/base.html natvrdo nastavovalo <html lang="en"> na každé stránce webu. Zveřejněná česká stránka pod touto šablonou by čtečkám obrazovky a vyhledávačům hlásila nesprávný jazyk, což je skutečná vada přístupnosti (WCAG 3.1.1), takže lang se nyní odvozuje z deklarovaného jazyka stránky a výchozí je angličtina. Vzájemné odkazy hreflang mezi stránkou a její protějškem v druhém jazyce se vydávají ze stejného front matteru.
Populace pravidla roste o kategorii, ne o výjimky. Zvažovanou alternativou bylo ponechat v1 a publikovat jen anglicky. To bylo zamítnuto, protože to činí dosah webu funkcí interního pravidla o pracovním jazyce, což je špatná osa: důvod, proč je angličtina povinná uvnitř repozitáře — že přispěvatel musí umět číst každý artefakt, který ho zavazuje — nic neříká o článku určeném někomu, kdo repozitář nikdy neotevře.
To, co zůstává nerozhodnutelné, se nemění a je stále uvedeno. Kontrola je test abecedy. Česká věta zapsaná v ASCII jím projde, ve v2 stejně jako ve v1, a pravidlo zůstává širší než kontrola. V2 přidává, že povolený případ je nyní typovaný a křížově ověřený, místo aby byl nemožný.