Locale — mi ez, Foundation osztály és lokalizáció

Mi az a Locale a Foundation-ben?

Locale — egy value-típus Swiftben (NSLocale Objective-C-ben), amely egy adott nyelvre és régióra jellemző formázási szabályok halmazát képviseli. A TimeZone-tól eltérően, amely az idő abszolút eltolódását határozza meg, a Locale határozza meg, hogy az idő, a számok és a pénznem hogyan jelennek meg szöveges formában. Ugyanaz a 2024-07-21 dátum „2024. július 21.„ formában jelenik meg ru_RU esetén és „July 21, 2024„ formában en_US esetén.

Minden Locale példány két komponensből áll: Language (nyelv — meghatározza a hónapok, hét napjainak nevét, szórendet) és Region (régió — meghatározza a számformátumot, pénznemet, naptárat). Ezen komponensek kombinációja a BCP 47 szabvány szerint van kódolva az azonosítóban: ru_RU (orosz nyelv, Oroszország), en_US (angol, USA), de_DE (német, Németország).

A Unicode CLDR (2024) szerint a támogatott lokalizációk listája iOS-en meghaladja a 700 nyelv-régió kombinációt. A Foundation a CLDR (Common Locale Data Repository) adatait használja — a lokalizációs adatok legteljesebb tárházát, amelyet az Unicode Consortium támogat. Ez garantálja a formázás egységességét minden Apple eszközön.

Hogyan befolyásolja a Locale a dátumok és számok formázását?

DateFormatter a Locale-t használja a hónapok és hét napjai helyes neveinek kiválasztásához, a dátumkomponensek sorrendjének (nap/hónap/év vagy hónap/nap/év) és elválasztóknak a meghatározásához. A Locale explicit megadása nélkül a DateFormatter az eszköz helyi beállítását használja — ez a UI számára helyes, de a szerveradatoknál veszélyes, ahol a formátumnak rögzítettnek kell lennie.

NumberFormatter a Locale-t használja a tizedes elválasztó (vessző vagy pont), a csoportosító elválasztó (szóköz, vessző, pont) és a pénznem szimbólumának meghatározásához. A Locale figyelmen kívül hagyása a számok értelmezésekor az egyik gyakori hibaforrás a nemzetközi alkalmazásokban: az „1,5„ szám ru_RU esetén „egy és fél„-et jelent, de en_US esetén a számelemző „öt„-ként olvassa a vessző után.

Fontos: A Calendar.current-en keresztül létrehozott Calendar örökli az eszköz helyi beállítását. A Calendar(identifier: .gregorian) explicit megadott locale-ral — az ajánlott módszer a kiszámítható formázáshoz. Az ISO 8601 dátumokkal való munka során mindig használja a Locale(identifier: "en_US_POSIX")-t — egy speciális helyi beállítást a technikai formázáshoz, amely nem áll a regionális beállítások hatása alatt.

Locale-azonosítók: alapformátumok

A Locale azonosító nyelvi kódból (ISO 639-1, két karakter) és régiókódból (ISO 3166-1, két karakter) áll, aláhúzásjellel elválasztva. Példák: ru_RU, en_US, fr_FR, zh_Hans_CN (kínai, egyszerűsített írás, Kína). A Foundation támogatja a BCP 47 formátumú azonosítókat is: ru-RU, en-US, amelyeket a webes szabványok használnak.

A teljes azonosítókon kívül a Locale csak nyelv alapján is létrehozható: a Locale(identifier: "ru") visszaad egy helyi beállítást orosz nyelvvel és az ehhez a nyelvhez tartozó alapértelmezett régióval (általában Oroszország). Hasonlóan angolra: a Locale(identifier: "en") az USA régióját használja. Ez a megközelítés hasznos a formázási nyelv beállításához anélkül, hogy egy adott régióhoz kötnénk.

Speciális helyi beállítások közé tartozik az en_US_POSIX — egy technikai helyi beállítás a dátumok és számok gépi formázásához, amely stabil formátumot garantál a felhasználói beállításoktól függetlenül. Ez a helyi beállítás kötelező a szerver API-kból származó dátumok értelmezéséhez, különösen az ISO 8601 formátum esetében. Gergely-naptárat, 24 órás időformátumot és pontot használ tizedes elválasztóként.

import Foundation

// Elérhető helyi beállítás azonosítók
let available: [String] = Locale.availableIdentifiers
print("Összes helyi beállítás: \(available.count)")

// Orosz helyi beállítások szűrése
let russianLocales = available.filter { $0.hasPrefix("ru") }
print("Orosz helyi beállítások: \(russianLocales)")

// Helyi beállítás komponensei
let locale = Locale(identifier: "de_DE")
print("Nyelv: \(locale.languageCode ?? "nil")")
print("Régió: \(locale.regionCode ?? "nil")")
print("Pénznem: \(locale.currencyCode ?? "nil")")
print("Naptár: \(locale.calendar.identifier)")

Elérhető helyi beállítások ellenőrzése a Locale.availableIdentifiers-en keresztül visszaadja az iOS aktuális verziója által támogatott összes azonosító tömbjét. A régió szerinti szűréshez használja a Locale.availableIdentifiers.filter-t a regionCode ellenőrzésével. Ez hasznos a régióválasztó UI felépítéséhez keményen kódolt lista nélkül.

A felhasználó aktuális helyi beállításának meghatározása Swiftben

Locale.current — az elsődleges módja az eszköz aktuális helyi beállításának lekérésére, amelyet a felhasználó az iOS beállításaiban (Settings > General > Language & Region) állít be. Ez a tulajdonság automatikusan frissül a nyelv vagy régió beállításokban történő megváltoztatásakor, az alkalmazás újraindítása nélkül. Azonban előfordulhat, hogy nem egyezik a tartalom megjelenítéséhez előnyben részesített helyi beállítással: a felhasználó beállíthatja a felület nyelvét angolra, de a dátumokat orosz formátumban nézheti.

A felhasználói preferenciák pontosabb meghatározásához használja a Locale.preferredLanguages-t — a felhasználói prioritás szerint rendezett nyelvek tömbjét. Az első elem a fő felületi nyelv. Ez a lista megfelel a Language & Region beállításainak, beleértve a nyelvek preferenciasorrend szerinti húzását. A kommunikációs alkalmazások (üzenetküldők, e-mail kliensek) vegyék figyelembe ezt a sorrendet a tartalom megjelenítési nyelvének kiválasztásakor.

import Foundation

// Aktuális rendszerhelyi beállítás
let current = Locale.current
print("Aktuális helyi beállítás: \(current.identifier)")
print("Nyelv: \(current.language?.disjointName ?? "nil")")

// Felhasználó által preferált nyelvek
let preferred = Locale.preferredLanguages
print("Preferált nyelvek: \(preferred)")

// Régió lekérése az aktuális helyi beállításból
if let region = current.regionCode {
    let regionLocale = Locale(identifier: "en_\(region)")
    let countryName = regionLocale.localizedString(
        forRegionCode: region
    )
    print("Ország: \(countryName ?? region)")
}

// 24 órás formátum ellenőrzése
let uses24h = current.uses24hClock(
    for: .dateAndTime
)
print("24 órát használ: \(uses24h)")

Lokalizáció a UI-ban: a hónapok és hét napjai neveinek a felület nyelvén történő megjelenítéséhez használja a Calendar-t beállított locale-ral. A Calendar.current.symbols(for: .month) visszaadja a hónapok neveit az aktuális helyi beállítás nyelvén. Az országnevek felhasználói nyelven történő megjelenítéséhez használja a Locale.current.localizedString(forRegionCode:)-t.

Locale Swiftben: használati példák

Dátum formázása a helyi beállítás figyelembevételével — kulcsfontosságú feladat a dátumok felhasználó számára történő megjelenítésekor. A DateFormatter a beállított locale-ral automatikusan kiválasztja a megfelelő dátum- és időformátumot a felhasználó régiójához. A dateStyle és timeStyle .short, .medium, .long, .full értékeihez a formázó a helyi beállítás szabályait használja a dátumkomponensek összeállításához.

import Foundation

let date = Date()

// Formázás különböző helyi beállításokkal
let formatter = DateFormatter()
formatter.dateStyle = .medium

formatter.locale = Locale(identifier: "ru_RU")
print("Orosz: \(formatter.string(from: date))")

formatter.locale = Locale(identifier: "en_US")
print("Angol: \(formatter.string(from: date))")

formatter.locale = Locale(identifier: "ja_JP")
print("Japán: \(formatter.string(from: date))")

// Pénznem formázása helyi beállítással
let numFormatter = NumberFormatter()
numFormatter.numberStyle = .currency

numFormatter.locale = Locale(identifier: "de_DE")
print("Német pénznem: \(numFormatter.string(from: 1234.56) ?? "nil")")

numFormatter.locale = Locale(identifier: "en_US")
print("Amerikai pénznem: \(numFormatter.string(from: 1234.56) ?? "nil")")

Dátumok értelmezése szerver API-kból mindig a Locale(identifier: "en_US_POSIX")-t kell használnia a rögzített formátumhoz. A szerverek általában ISO 8601 formátumban küldenek dátumokat angol hónapnevekkel, és az eszköz aktuális helyi beállításának használata értelmezési hibához vezethet, ha a felhasználó nem angol nyelvű régióban van. Az en_US_POSIX garantálja, hogy az értelmezés nem függ az eszköz beállításaitól.

import Foundation

// Szerver dátumok helyes értelmezése
let isoFormatter = DateFormatter()
isoFormatter.dateFormat = "yyyy-MM-dd'T'HH:mm:ssZ"
isoFormatter.locale = Locale(identifier: "en_US_POSIX")
isoFormatter.timeZone = TimeZone(secondsFromGMT: 0)

let serverDate = "2024-07-21T14:30:00+0000"
if let parsed = isoFormatter.date(from: serverDate) {
    print("Értelmezett dátum: \(parsed)")
}

// Lokalizált pénznem név
let usLocale = Locale(identifier: "en_US")
let currencyName = usLocale.localizedString(
    forCurrencyCode: "RUB"
)
print("Orosz rubel amerikai helyi beállításban: \(currencyName ?? "nil")")

További lehetőségek: A Locale lokalizált leírást nyújt komponenseiről a localizedString(forRegionCode:), localizedString(forLanguageCode:), localizedString(forCurrencyCode:) és localizedString(forCalendarIdentifier:) metódusokon keresztül. Ezek a metódusok a meghívás helyi beállításának nyelvén adják vissza a neveket. Például a Locale(identifier: "ru_RU").localizedString(forCountryCode: "DE") „Németország„-ot ad vissza.

Gyakori hibák a Locale használatakor

A Locale figyelmen kívül hagyása a számok értelmezésekor — kritikus hiba a nemzetközi alkalmazásokban. A NumberFormatter explicit helyi beállítás nélkül az eszköz aktuális helyi beállítását használja. Ha egy felhasználó Oroszországban beírja az „1,5„-öt, a NumberFormatter.number(from: "1,5") helyesen 1.5-öt ad vissza. De ha ugyanez a kód egy en_US helyi beállítású eszközön fut, az értelmezés nil-t ad vissza, mert en_US esetén a tizedes elválasztó a pont.

Az en_US_POSIX hiánya a szerver dátumokhoz nehezen észlelhető hibákhoz vezet. A DateFormatter dateFormat és locale = Locale.current paraméterekkel meghibásodhat azoknál a felhasználóknál, akik olyan régióban vannak, ahol a dátumformátum eltér az amerikaitól. Például Németországban a DateFormatter „21.07.2024„-et várhat, míg a szerver „07/21/2024„-et küld. Az en_US_POSIX rögzített formátumot garantál a gépi értelmezéshez, függetlenül a felhasználó régiójától.

Dátumstringek összehasonlítása a Date használata helyett — egy másik gyakori hiba. A fejlesztők néha összehasonlítják a dátumok szöveges megjelenítéseit különböző helyi beállításokból, helytelen eredményeket kapva. A Locale csak a megjelenítést változtatja, nem a dátum abszolút értékét. Mindig Date objektumokat hasonlítson össze, ne azok szöveges megjelenítéseit. A dátumkomponensek összehasonlításához használjon Calendar-t explicit megadott locale-ral.

A WWDC 2023 szerint az alkalmazásokban előforduló internacionalizációs problémák körülbelül 30%-a a Locale helytelen konfigurációjához kapcsolódik. Az Apple azt javasolja, hogy mindig explicit módon adja meg a locale-t a DateFormatter és NumberFormatter számára a szerveradatokkal való munka során, és csak a UI-ban történő megjelenítéshez használja a Locale.current-et. Ez az egyszerű gyakorlat kiküszöböli a regionális beállításokkal kapcsolatos hibák többségét.