10 Common i18n Mistakes Developers Make | Fix Guide 2025

A nemzetközivé tétel (i18n) egyszerűnek tűnik — amíg rá nem ébredsz, hogy német felhasználóid levágott gombokat látnak, a japán felhasználók torzított mondatrészeket kapnak, és az arab beszélő felhasználók teljesen rossz elrendezéssel találkoznak. Ezek nem kivételes esetek. Ezek a leggyakoribb hibák előre látható következményei, amelyeket a legtöbb fejlesztőcsapat elkövet, amikor először áll hozzá a lokalizációhoz. Ebben az útmutatóban a 10 leggyakoribb i18n hibát tárgyaljuk, pontosan megmagyarázzuk, miért fordulnak elő, és lépésről lépésre megmutatjuk, hogyan javítsd ki mindegyiket. Akár egy új alkalmazást építesz, akár egy meglévőt korszerűsítesz — ezeknek a csapdáknak a elkerülése hetek helyett napokat spórol meg neked.

Hiba #1: Kódolt szövegek

A hardkodolt stringek az i18n legalapvetőbb hibája. Akkor fordul elő, amikor a fejlesztők először azon dolgoznak, hogy a funkciók működjenek, és úgy terveznek, hogy 'később rendbe tesszük'. De a késő soha nem jön el, és hirtelen ezer szöveg kerül feltöltésre több száz fájlban.

['Állítsa be az i18n keretrendszert az első UI-kódsor megírása előtt', 'Használjon lint-plugin-t a hardkodolt stringek felismerésére sablonokban és komponensekben', 'Tartsa a fordítási kulcsokat leíró és rendezett funkció/szint szerint']

Az i18n keretrendszert állítsd be, mielőtt az UI kód első sorát megírod.

Használd a Linter plugint, hogy felismerd a hardkodolt szövegeket sablonokban és komponensekben.

A fordítás kulcsokat legyen leíróak és rendezze őket funkció szerint vagy oldalanként.

Tipikus forgatókönyv

Fejlesztő egy gomb feliratát közvetlenül JSX-ben írja: <button>Submit Order</button>.

Az alkalmazás angol nyelven érkezik és hibátlanul működik. Hét hónappal később a vállalat Németország felé bővül.

A lokalizációs csapat több mint 2 000 hardkodolt szöveget talál. A pótlás 3 hétig tart, és 47 hibát okoz.

Miért ez probléma

Kiforrott kódbázisban a hardkodolt stringek ezreire rúghatnak. Utólagos kivonás azt jelentené, hogy érintenie kell minden fájlt, újra kell tesztelni minden összetevőt és kockáztatni visszatérő problémákat mindenhol.

A hardkodolt stringek közvetlenül a forráskódban, sablonokban vagy komponensekben vannak beágyazva. Nem vonhatók ki, lefordíthatók vagy futási időben cserélhetők anélkül, hogy a kódot megváltoztatnánk.

Az angolul nem beszélő felhasználók olyan UI-elemeket látnak, amelyek nincsenek lefordítva, vegyítve a lefordított tartalommal — kaotikus és nem professzionális benyomás.

Így oldhatod meg

Helyezze át a felhasználók által látott összes stringet már a kezdetektől fogva erőforrásfájlokba.

Rendszeresítsen egy fordítási keretrendszert (például next-intl, react-i18next, vue-i18n) az első komponens megírása előtt.

Hozzon létre erőforrásfájl-struktúrát (pl. messages/de.json), és hivatkozzon minden stringre fordítási kulcsokkal, például t('checkout.submitButton').

Adjon hozzá linting-szabályt vagy pre-commit hook-ot, amely a nyers string-literalokat jelzi a UI-komponensekben.

Hiba #10: Minden szöveg szó szerint lefordítása

Nem minden tartalom legyen lefordítva. Márkanévek, jogi személyek nevei, technikai kifejezések és bizonyos terméknevek az eredeti nyelvükön maradjanak. Túlzott fordítás jogi problémákat, a márka konzisztenciájának hiányát és felhasználói zavart okozhat.

["Tarts egy 'Ne fordítsd le' szótárt és oszd meg minden fordítóval", "Használj külön névteret vagy speciális kulcsokat a nem lefordítandó tartalmakhoz", "Mindig adj kontextus-megjegyzéseket a többértelmű stringekhez a téves fordítások megelőzése érdekében"]

Tartsa karban a 'ne fordítsd' szószedetet és ossza meg minden fordítóval.

Használjon zárt szegmenseket vagy külön namespace-eket a márka- és jogi terminológiához.

Mindig adjon kontextusmegjegyzéseket a többértelmű karakterláncokhoz, hogy elkerülje a rossz fordításokat.

Egy tipikus helyzet

Egy fordítási fájl tartalmazza a 'CloudForge Inc.' vállalatnevet és a 'OAuth 2.0 Token' technikai kifejezést mint általános fordítható stringeket.

A spanyol fordító a 'CloudForge'-t 'ForjaNube'-ként, és az 'OAuth 2.0 Token'-t 'ficha OAuth 2.0'-ként fordította.

Eredmény: a felhasználók nem találják meg a céget a valódi nevével, és a spanyol dokumentációt olvasó fejlesztők zavartak az ismeretlen, lefordított technikai kifejezésektől.

Miért jelent problémát

Egy jogi dokumentumban rosszul lefordított márkanév érvénytelenítheti a szerződést. A túlzott fordítások kijavítása megkívánja minden szöveg ellenőrzését minden nyelven — többhetes munka.

Ha az összes szöveg kontextus nélkül kerül lefordításra, a fordítók előfordulhat, hogy márkaneveket ('Apple' → 'Apfel'), jogi terminusokat ('GmbH' → 'LLC') vagy olyan technikai kifejezéseket fordítanak le, amelyek angolul kell maradjanak.

Felhasználók nem találják termékeiket a megszokott márkanév alatt, jogi dokumentumok a helytelen társaságra hivatkoznak, és a technikai dokumentáció érthetőtlenné válik, ha olyan kifejezéseket, mint az 'API Endpoint', lefordítanak.

Hogyan javítsd ki ezt

Jelöld egyértelműen a nem lefordítható tartalmakat, és adj kontextusmegjegyzéseket a fordítók számára.

Hozz létre egy 'Ne Fordítsd Le' glosszáriót, amely felsorolja minden márkanév, terméknév, jogi személy és szakmai kifejezés, amelyet változtatás nélkül kell megtartani.

Használj külön névteret vagy speciális kulcsokat a nem lefordítandó tartalmakhoz. Sok i18n eszköz támogatja a 'zártként' kezelt szegmenseket, amelyeket a fordítók nem szerkeszthetnek.

Fordító megjegyzéseket/tartalmi leírásokat adj a fordítási fájljaidhoz, amelyek megmagyarázzák a kontextust: 'Ez egy márkanév — ne fordítsd le' vagy 'Szakmai kifejezés — angolul hagyd'.

Hiba #2: Szövegek összefűzése

A mondatokat fragmentumokból összerakni angolul logikusnak tűnhet, de más nyelveken nem működik. A szórend, a nyelvtan és a mondatszerkezet nyelvről nyelvre drámaian eltérő, így az összefűzött stringek lefordíthatatlanná válnak.

['Soha ne építs mondatokat fordított fragmentumok összefűzésével', 'Használj nevezett helyettesítőket ('{name}') a pozíciós helyett ({0}) helyett a világoság érdekében', 'Biztosíts fordítói kontextus kommenteket, amelyek elmagyarázzák, mit tartalmaz minden helyettesítő']

Soha ne alkoss mondatokat fordított töredékek összeillesztésével.

Használj nevezett helyettesítőket ('{name}') a pozíciós helyett ({0}) a világoság érdekében

Biztosítson kontextusmegjegyzéseket a fordítók számára, amelyek elmagyarázzák, hogy minden helykitöltő mit tartalmaz.

Egy tipikus forgatókönyv

Fejlesztő azt írja: 'You have ' + count + ' items in your ' + cartType + ' cart' — angolul tökéletesen működik.

A német fordító három külön részre kap és nem tud helyes mondatot alkotni, mert a szórend megváltoztatása szükséges.

Eredmény: a német felhasználók látják a 'Sie haben 5 Artikel in Ihrem Warenkorb Standard' szöveget — döcögős és nem professzionális.

Miért ez probléma

Minden összefűzött string időzített bomba. 20 nyelvnél és 50 összefűzött stringnél 1 000 potenciális nyelvtani hiba van, amelyeket manuálisan ki kell javítani.

Olyan stringek összefűzése, mint a 'Willkommen ' + userName + ', du hast ' + count + ' neue Nachrichten' bizonyos szórendet igényel. A fordítók összefüggéstelen fragmentumokat kapnak, amelyeket nem tudnak átstrukturálni.

Felhasználók nyelvtanilag helytelen mondatokat látnak. Németországban az ige általában a mondat végén áll. Az arab nyelvben a teljes szerkezet megfordul. Az eredmény olvasva értelmetlennek tűnik.

Így javíthatod ki

Használj névvel ellátott helyettesítőket a teljes mondat átrendezéséhez.

Cseréld le az összefűzést egy egyedi üzenetkulcsra helyettesítőkkel: 'cart.summary': 'A '{cartType}' kosaradban {count} tétel van'.

A változókat paraméterekként adhatod át a fordítási függvénynek: t('cart.summary', { count: 5, cartType: 'Premium' }).

A fordítók most szabadon átrendezhetik: 'A '{cartType}' kosaradban {count} tétel van' — nyelvtanilag helyes német.

Hiba #3: Többes szám figyelmen kívül hagyása

Az angolnak két többes szám alakja van: egyes szám és többes szám. A fejlesztők gyakran feltételezik, hogy minden nyelv ugyanolyan módon működik. Nem így van. A lengyelnek 4 alakja van, az arabnak 6, s még olyan nyelvek, mint a francia, az nullát a angolhoz hasonlóan kezeli.

['Mindig használja ICU MessageFormat-et vagy hasonló könyvtárat a számolható tartalmakhoz', 'Soha ne írj saját többes szám logikát — bízz a CLDR szabályokban', 'Teszteld a többes számot olyan értékekkel, mint 0, 1, 2, 5, 21 és 100, hogy lefedd minden kategóriát']

Mindig használja az ICU MessageFormat-et vagy egy ekvivalens könyvtárat számlálható tartalmakhoz.

Soha ne írjon saját többes szám logikát — bízzon a CLDR szabályokban.

Tesztelje a többes számot olyan értékekkel, mint 0, 1, 2, 5, 21 és 100, hogy minden kategóriát lefedjen.

Egy tipikus forgatókönyv

Fejlesztő írja: count + (count === 1 ? ' Datei' : ' Dateien') — németül helyes.

A lengyel fordító 4 formát igényel: 1 plik, 2-4 pliki, 5-21 plików, 22-24 pliki. Az egyszerű ternáris ezt nem képes kifejezni.

Eredmény: a lengyel felhasználók a '5 pliki' (helytelen forma) helyett a '5 plików' (helyes forma) látják, és az alkalmazás hibásnak tűnik.

Miért probléma ez

Minden számlálható főnévhez a alkalmazásodban plurálkezelés szükséges. 50 ilyen string és 20 nyelv esetén 1 000 plurális szabály van — manuálisan kezelhetetlen.

Egyszerű if/else ellenőrzések (count === 1 ? 'Datei' : 'Dateien') csak németet/angolt kezelnek. A CLDR definiál akár 6 plurális kategóriát: zero, one, two, few, many és other. Minden nyelv egy másik al-készletet használ.

A felhasználók olyan nyelvtani hibákat tartalmazó szövegeket látnak, mint a '1 Nachrichten', vagy teljesen helytelen plurális formák. Formális kontextusokban ez rontja a hitelességet.

Így javíthatod

Használd az ICU MessageFormat-et, amely beépített módon támogatja a CLDR plurális szabályait.

Határozd meg az üzeneteket ICU-szintaxissal: 'fileCount': '{count, plural, one {# Datei} other {# Dateien}}'.

A fordítók biztosítják nyelvükhöz a szükséges plurális formákat. Lengyel: '{count, plural, one {# plik} few {# pliki} many {# plików} other {# pliku}}'.

Az i18n-könyvtárad futás közben automatikusan az aktív locale CLDR-szabályainak megfelelő alakot választja.

Hiba #4: Feste UI-Element-Breiten

A tervezők angol nyelvű pixel pontosságú elrendezéseket készítenek, és a fejlesztők ezeket rögzített szélességekkel valósítják meg. De a lefordított szöveg drámaian hosszabb vagy rövidebb lehet. A német szöveg kb. 30%-kal hosszabb, mint az angol, míg a kínai szöveg akár 50%-kal rövidebb is lehet.

['Soha ne használjon fix pixel-szélességet az lefordítható szöveget tartalmazó elemeknél', 'Tervezzen 40%-os szövegnövekedést baseline-ként — egyes nyelvek még többet bővülnek', 'Használja a CSS Flexbox-ot vagy Grid-et olyan elrendezésekhez, amelyek alkalmazkodnak a változó tartalomhoz']

Soha ne használjon rögzített pixell szélességet olyan elemeknél, amelyek fordítható szöveget tartalmaznak.

Tervezzen 40%-os szöveg-bővítést kiindulási alapként — egyes nyelvek még tovább bővülnek.

Használja a CSS Flexbox-ot vagy Gridet olyan elrendezésekhez, amelyek a változó tartalom hosszához igazodnak.

Egy tipikus helyzet

A tervező egy navigációs sávot készít 5 gombbal, mindegyik pontosan 100px széles — angol verzióban jól néz ki.

Német fordítás: 'Settings' 'Einstellungen'-é válik (13 vs 8 karakter), 'Submit' pedig 'Absenden'-né válik (8 vs 6). A navigációs sáv túlcsúszik.

Eredmény: Mobil eszközökön a gombok egymásra kerülnek vagy a szöveg levágódik, ami a német felhasználók számára a navigációt használhatatlanná teszi.

Miért probléma ez

Minden fix szélességű elem potenciális töréspont. Egy tipikus alkalmazásban százak gomb, címke és kártya van, amelyek mind a szöveg bővítését ki kell bírniuk.

Fix szélességű konténer (width: 120px) és fix méretű gombok kivágódnak vagy túlcsordulnak, ha a szöveg kitágul. A CSS overflow: hidden csendben elrejti a tartalmat, míg az overflow: visible tönkreteszi a layoutot.

Felhasználók olyan vágott feliratokat láthatnak, mint 'Einstellu...' ahelyett, hogy 'Einstellungen' lenne, vagy olyan gombokat, amelyek átfedik a szomszédos elemeket. Kritikus műveletek olvashatatlanná vagy kattinthatatlanná válnak.

Így javíthatod ki

Készítsen és valósítson meg rugalmas elrendezéseket, amelyek alkalmazkodnak minden locale tartalmának hosszához.

A fix szélességeket cserélje ki min-width, max-width és Flex-Layouts-ra. Helyet dinamikusan oszd el a CSS Grid vagy Flexbox segítségével.

Írja be a szövegtárolót tördelésre: használja az overflow-wrap: break-word-et és kerülje a white-space: nowrap-ot lefordítható szöveg esetén.

Az UI-t tesztelje pseudo-lokalizációval, amely minden szöveget 40%-kal meghosszabbítja, hogy a legrosszabb esetet szimulálja — még mielőtt a szövegeket a fordítóknak küldené.

Hiba #5: Dátum- és számformázás

Az adatok és számok látszólag univerzálisak. De 01/02/2025 az USA-ban 2. január és Európában 1. február. A vesszők és a pontok a számoknál jelentésüket felcserélik: 1,000.50 (USA) vs 1.000,50 (Németország). Ezt rosszul csinálva összezavarodást, adathibákat és bizalomvesztést okoz.

['Az elejétől kezdve kizárólag logikus CSS-tulajdonságokat használjon (inline-start/end, block-start/end)', 'Minden sprint-áttekintésnél tesztelje az alkalmazást a HTML-elem dir='rtl' beállításával', 'Készítsen RTL-tesztlistát a navigációhoz, ikonokhoz, űrlapokhoz és a haladást jelző elemekhez']

Soha ne formázzon adatokat vagy számokat manuálisan string sablonokkal — mindig használja az Intl API-kat.

Belsőleg minden adatot ISO 8601-ben és a valutákat a legkisebb egységben (cent) tároljon.

Tesztelje különböző lokalokkal, amelyek különböző tizedesjelek, dátum sorrendek és különböző naptár rendszerek használatát.

Egy tipikus helyzet

Fejlesztők dátumot MM/DD/YYYY formátumban és árat $1,234.50 formátumban adnak meg — helyes az USA-felhasználók számára.

Német fordítás: 'Settings' 'Einstellungen'-é válik (13 vs 8 karakter), 'Submit' pedig 'Absenden'-né válik (8 vs 6). A navigációs sáv túlcsúszik.

Eredmény: a felhasználó egy rossz dátumra foglal repülőjegyet és megkérdőjelezi az ár formátumát. A német piacon a támogatási jegyek száma 15%-kal nő.

Miért probléma ez

A dátumok és számok formázása minden adat-megjelenítést érint az alkalmazásodban: táblázatok, diagramok, űrlapok, számlák, jelentések. Egy globális javítás több száz példányt érint.

Kódolt formátum stringek, mint a toLocaleDateString('en-US') vagy a sablon-literalákkal végzett kézi formázás figyelmen kívül hagyja a felhasználó tényleges locale-ját. Még ha a helyes locale is megvan, a helytelen naptármendszer (Gregorian vs Hijri) problémákat okoz.

A felhasználók helytelenül olvassák az adatokat, és hibás formátumban adnak meg adatokat. Egy európai felhasználó, aki 03/04/2025-öt lát, talán úgy értelmezi, hogy az 3. április a 4. március helyett — elhalasztott találkozók vagy hibás foglalások.

Így javíthatod meg

Használd a beépített Intl-API-t vagy egy locale-tudatos formázó könyvtárat minden dátumhoz, időhöz, számhoz és valutához.

A manuális formázást cseréld le az adatokhoz az Intl.DateTimeFormat(locale) használatával, a díjakhoz pedig az Intl.NumberFormat(locale, { style: 'currency', currency }) használatával.

Belsőleg tárold az adatokat ISO 8601 formátumban (YYYY-MM-DD), és csak a megjelenítéshez formázd őket a felhasználó locale-jának megfelelően.

Legalább 5 különböző lokációval tesztelje a dátumok és számok kritikus megjelenítését: en-US, de-DE, ja-JP, ar-SA és zh-CN, hogy lefedje a legfontosabb formázási variációkat.

Hiba #6: RTL-nyelvek figyelmen kívül hagyása

RTL-támogatás minden egyes komponensre hat az alkalmazásban. Az RTL támogatás utólagos bevezetése általában a CSS 30-50%-ának újraírását és minden ikon és elrendezés ellenőrzését igényli.

Az első naptól kezdve kizárólag logikai CSS-tulajdonságokat használjon (inline-start/end, block-start/end).

Készítsen RTL-tesztlistát a navigációhoz, ikonokhoz, űrlapokhoz és a haladásjelzőkhöz.

Egy tipikus forgatókönyv

Fejlesztő az egész alkalmazásban margin-left: 16px és text-align: left használatával — az LTR alapvető gyakorlat.

Az alkalmazás Szaúd-Arábiában indul. A visszafelé nyilak előre mutatnak, az oldalsávok a rossz oldalon jelennek meg, és a numerikus adatok nincsenek helyesen igazítva.

Eredmény: Arab felhasználók 30 másodpercben belül kilépnek az alkalmazásból. A csapatnak 4 hét CSS-refaktorálásra van szüksége a probléma megoldásához.

Miért jelent ez problémát?

Az RTL-támogatás minden egyes komponensre hat az alkalmazásban. Az RTL későbbi bevezetése általában a CSS 30-50%-ának újraírását és minden ikon és elrendezés ellenőrzését igényli.

CSS-tulajdonságok, mint margin-left, padding-right, text-align: left és float: left véglegesen kódolják az irányt. Irányítottsággal rendelkező ikonok a rossz irányba mutatnak. Még a border-radius értékei is tükrözniük kellene.

Arab felhasználók a navigációt a helytelen sarokban látják, az előre haladó folyamat visszafelé fut, és a szöveg ütközik a UI elemekkel. Az alkalmazás idegennek és használhatatlannak tűnik.

Így javíthatod meg

Használd a logikus CSS-tulajdonságokat, és kezdetektől fogva teszteld RTL-elrendezéssel.

Az összes fizikai CSS-tulajdonságot cseréld le logikus megfelelőkre: margin-left → margin-inline-start, padding-right → padding-inline-end, text-align: left → text-align: start.

Állítsd be a dir attribútumot a HTML-gyökér elemén a kiválasztott locale alapján. Használd a :dir(rtl) CSS-pseudo-osztályt RTL-specifikus felülírásokhoz.

Ellenőrizd az összes ikont irányjelölés szempontjából. Cseréld le az iránytól függő ikonokat tükrözött verziókra, vagy használd a CSS transform: scaleX(-1) RTL-környezetekhez.

Hiba #7: Képeken lévő szöveg

Szöveg beépítése képekbe — legyen az hős banneren, gombokon, infografikákon vagy képernyőmentéseken — i18n rémálom. Minden képhez szöveggel minden nyelvre külön újra kell készíteni, ami növeli a dizájnköltségeket és késlelteti a kiadásokat.

['Soha ne illessük közvetlenül raszterképekre a lefordítható szöveget (PNG, JPG)', 'Használd a CSS szöveges overlays-t a háttérképeken a hős bannerekhez és a CTA-khoz', 'Automatizáld a képernyőképek generálását App Store listingek és marketing oldalakhoz']

Soha ne illessze közvetlenül fordítható szöveget raszterképekbe (PNG, JPG).

Használja a CSS szövegfedő rétegeit a háttérképeken a hős bannerekhez és a CTA-khoz.

Automatizálja a képernyőképek generálását az App Store-listákhoz és a marketingoldalakhoz.

Egy tipikus forgatókönyv

Egy tervező létrehoz egy promóciós bannert a 'Start Your Free Trial' szöveggel, amely közvetlenül a képre van ágyazva.

A helyi fejlesztő csapat minden UI-szöveget lefordít, de a német oldalon a banner továbbra is angol szöveget mutat.

Eredmény: a német landoló oldal egy zavaró angol bannert tartalmaz. Az 15 nyelvre lokalizált bannerek elkészítése 3 napos tervezési munkát igényel, és késlelteti a bevezetést.

Miért jelent ez problémát?

Egy tipikus marketingoldal 5-10 képet tartalmaz szöveggel. 15 nyelv esetén ez 75-150 képvariánst jelent, amelyeket létre kell hozni, karbantartani és minden dizájnváltoztatásnál frissíteni kell.

Képbe ágyazott szöveg (PNG, JPG, SVG beágyazott szöveggel) nem érhető el fordítóeszközökkel. Bármely helyi verzióhoz a tervezőnek manuálisan kell szerkesztenie a forrásfájlt, exportálnia és feltöltenie.

A felhasználók idegen nyelvű szöveget tartalmazó képeket látnak, vagy még rosszabbul, a fordított felület és a le nem fordított képek keverékét. Ez konzisztenciátlanul hat, és aláásja a márka iránti bizalmat.

Hogyan oldod meg ezt

Tedd el a szöveget a képektől CSS felülírásokkal, SVG-kkel, amelyek fordítható szöveg elemeket referálnak, vagy dinamikus kép generálással.

Használd a CSS-t, hogy a lefordított szöveget a háttérképek fölé tedd: helyezd el a szöveg réteget abszolút pozícionálással a kép tartálya fölé.

Infografikák vagy diagramok esetén használj SVG-ket <text> elemekkel, amelyek a fordítási kulcsokat referenciálják, ne pedig nyers szöveget építs be.

Az App Store-listingek és marketingoldalak képernyőképeinek automatikus generálását állítsd be, hogy minden locale tartalmazzon képernyőképeket.

Hiba #8: Hiányzó fordítások nincsenek kezelve

A fordítások a fejlesztés során mindig hiányosak. Az új funkciók gyorsabban adnak hozzá szövegeket, mint a fordítók lefordíthatják őket. Megfelelő fallback-logika nélkül a hiányzó fordítások összeomláshoz, üres UI-elemekhez vagy a felhasználók által látott nyers fordítás-kulcsokhoz vezethetnek.

['Mindig állíts be legalább egy fallback nyelvet az i18n-beállításaidban', 'Naplózd a hiányzó fordításkulcsokat a monitorozó rendszeredbe nyomon követés céljából', 'Állíts be minimális fordítás-fedezetet, mielőtt egy locale élőre kerülhet']

Mindig konfiguráljon legalább egy fallback nyelvet az i18n beállításokban.

Rögzítse a hiányzó fordítási kulcsokat a nyomon követő rendszerében.

Állítson be minimális fordítási lefedettséget, mielőtt egy locale élő lehet.

Egy tipikus forgatókönyv

Fejlesztők hozzáraknak egy új 'Premium Features' részt 15 új fordítási kulccsal. Az angol változat azonnal kiszállításra kerül.

A francia fordítások még nincsenek kész. A francia oldal nyers kulcsokat mutat: 'premium.feature1.title', 'premium.feature1.description'.

Eredmény: a francia felhasználók egy törött oldalt látnak, tele fejlesztői kulcsnevekkel. A támogató csapat tucatnyi hibajelentést kap.

Miért probléma ez

Az alkalmazás egyre nagyobb lesz, annál nagyobb a szakadék az angol szövegek és a többi nyelv fordításai között. Egy 100 nyelvet támogató alkalmazás és 2.000 szöveg esetén bármikor több mint 10.000 hiányzó fordítás lehet.

Fallback logika nélkül egy hiányzó fordítási kulcs undefined-et, null-t vagy a nyers kulcs stringet ad vissza (pl. 'checkout.confirmButton'). Sablonmotorok hibákat dobhatnak, az oldal összeomolhat, vagy semmit sem renderel.

A felhasználók hibás UI-t látnak: üres gombok, hiányzó címkék vagy 'nav.settings.title'-hez hasonló rejtélyes szöveg a tényleges szöveg helyett. Ez megtévesztő és nem profi.

Hogyan oldod meg ezt

Egy erős fallback láncot konfigurálj, és figyeld a fordítások lefedettségét minden locale-ban.

Az i18n konfigurációdban állíts be egy robusztus fallback nyelvi láncot: a hiányzó fr (fr) kulcsok automatikusan visszakerülnek angolra (en).

Adj hozzá egy hiányzó kulcsok kezelésőjét, amely a le nem fordított kulcsokat a monitorozó rendszeredbe (például Sentry, Datadog) naplózza, anélkül hogy a felhasználói élményt megszakadna.

Készíts egy Fordítási lefedettség-irányítót (dashboard), amely nyomon követi a teljesítési arányt minden locale-ra, és blokkolja a kiadásokat, ha a lefedettség egy küszöbérték alá esik (például 95%).

Hiba #9: Karakterkódolási problémák

Karakterkódolási problémák a lokalizáció csendes gyilkosaik. Minden rendben van angolul és európai nyelveken, de ha kínait, japánt, koreait, arabot vagy emojit adsz hozzá, torzított karakterek (Mojibake) jelennek meg. Ezek a hibák nehéz felderítésűek.

['Mindenhol UTF-8 kódolást használj — forrásfájlok, adatbázis, API-válaszok és HTML meta-tagek', 'Használd a utf8mb4-et MySQL-ben (nem csak az utf8-at), hogy a teljes Unicode-területet beleértve az emoji-t is támogasd', 'Tesztelj valódi tartalommal CJK, arab és emoji esetén, hogy korán észrevegyük a kódolási problémákat']

Használja a UTF-8 kódolást mindenhol — forrásfájlok, adatbázis, API-válaszok és HTML meta-tagek.

MySQL-ben használja a utf8mb4-et (nem utf8), hogy a teljes Unicode-tartományt támogató legyen, beleértve az emoji-t.

CJK, kínai és koreai (CJK), arab és emoji valós tartalommal tesztelje a kódolási problémák korai felismerése érdekében.

Egy tipikus helyzet

A fejlesztő egy MySQL adatbázist latin1-kollációval állít be (régió alapértelmezés). Az alkalmazás forráskódja UTF-8-at használ.

A japán felhasználók a valódi nevükkel regisztrálnak. Az adatbázis '田中太郎'-t hibás bájtokként tárolja.

Eredmény: a felhasználói profil torzult szöveget mutat. Még rosszabb: a keresés és rendezés minden CJK névre hibás lesz, ami több ezer felhasználót érint.

Miért jelent problémát

A karakterkódolási problémák az egész stackre kiterjednek. A helytelen adatbázis-kolláció millió rekordot tehet tönkre — a javítás költséges adat-migrációt igényel.

A karakterkódolás inkonzisztenciája a stackszerte — UTF-8 a forrásfájlokban, Latin-1 az adatbázisban és Windows-1252 az API-válaszban — tönkreteszi a többbites karaktereket. Egyetlen rosszul konfigurált réteg '日本語'-t '????' vagy 'æ—¥æœ¬èª' értékre változtathat.

Felhasználók torzult szövegeket, kérdőjeleket vagy üres négyzeteket látnak a nyelvük helyén. A legrosszabb esetben a űrlapok bevitele tartósan megsérülhet az adatbázisban.

Hogyan oldható meg

Következetesen alkalmazd az UTF-8 kódolást a teljes alkalmazás-stacken minden rétegében.

Az összes forrásfájlt állítsd UTF-8-ra (konfiguráld a szerkesztődet és a .editorconfig-et). Adj meg HTML-ben <meta charset='UTF-8'>-t és az API-válaszokban a 'Content-Type: application/json; charset=utf-8' beállítást.

Állítsd be az adatbázist utf8mb4-re (nem csak az utf8-re, mert az MySQL-ben 3 bájtos részhalmaz). Állítsd a kapcsolati kollációt utf8mb4_unicode_ci-re.

Válassz olyan betűtípusokat, amelyek lefedik a cél írási rendszereidet: latin, cirill, CJK, arab, devanagari. Használd a rendszer betűtípus-Stack-eket vagy a Google Fontokat nyelvi alcsoportokkal a gyorsabb betöltésért.

Az i18n-implementáció tesztelése

Hosszabbítás-teszt

A lefordított összes szöveget 30–40%-kal növeld meg, hogy szimuláld a szöveg bővülését olyan gazdag nyelvekben, mint a német, a finn vagy a görög. Ez lefedi a rögzített szélességű tartályokat, a levágott címkéket és a túlcsorduló gombokat is, mielőtt egyáltalán elkezded a fordítást. Sok pszeudo-lokációs eszköz beépített funkcióként kínálja ezt.

"Senden" → "Ṡééééñðéñ_éxpáñðéð" (40% hosszabb)

pszeudo-lokalizáció

Pseudó-lokáció minden karaktert akcentuált megfelelővel helyettesít (például 'a' → 'á') és a karakterláncokat olyan jelölésekkel veszi körül, mint [!! és !!]. Így azonnal láthatóvá válik, mely sorok vannak kódolva a forráskódban és melyek a fordítási rendszerből származnak. Futtasd a pseudó-lokálizációt a CI-pipeline részeként, hogy regressziókat automatikusan kiszűrj.

A képernyőn lévő minden szöveg, amely nem szerepel a [!! !!]-jelölések között, hardkódolt és ki kell vonni a kódból. Ez a teszt 95%-ban észleli a rejtett stringeket kevesebb mint egy perc alatt.

"Üzenet küldése" → "[!! Ñáçḥŕíçḥṫ ṡéñðéñ !!]"

RTL-elrendezés-teszt

Még akkor is, ha nincs arámi vagy héber fordítás, RTL-elrendezést tesztelhetünk úgy, hogy dir='rtl' értéket adunk a HTML gyökérelemhez. Ez közvetlenül feltárja a CSS irányítási hibákat: helytelen ikon-igazítás, oldalról helyes margó hiánya, nehezen navigálható és rosszul rendezett Flex-elemek. Tegyük ezt sztenderd ellenőrzéssé minden sprint-áttekintésben — 10 másodpercbe kerül a váltás, és olyan problémákat fog fel, amelyek egyébként hetekig tartottak volna a Productionban.

Az i18n-ellenőrzőlista

['Az összes felhasználói szemmel látható stringet erőforrásfájlokba helyeztük', 'Nem használunk string-összefűzést mondatok létrehozására', 'Pluralis szabályokat ICU MessageFormat vagy megfelelővel valósítottuk meg', 'Dátum-, idő- és számformázás locale-érzékeny API-kkal történik', 'RTL-elrendezést arab vagy héber tartalommal teszteltünk', 'Rugalmas UI dinamikus szélességekkel a szövegtartalom esetén', 'Alapértelmezett nyelv konfigurálva és hiányzó kulcsok esetén tesztelve', 'UTF-8 kódolás konzisztens minden fájlban és adatbázisban', 'Alkalmazás áruház és Google Play áruadatok piacra lokalizált', 'Képernyőképek és marketing-eszközök minden nyelvre frissítve']