Locale — ano ito, Foundation class at lokalisasyon

Ano ang Locale sa Foundation?

Locale — ay isang value-type sa Swift (NSLocale sa Objective-C) na kumakatawan sa isang set ng mga panuntunan sa pag-format na katangian ng isang partikular na wika at rehiyon. Hindi tulad ng TimeZone na tumutukoy sa absolute time offset, tinutukoy ng Locale kung paano lumilitaw ang oras, numero at pera sa string representation. Ang parehong petsa na 2024-07-21 ay ipapakita bilang "21 Hulyo 2024" para sa ru_RU at "July 21, 2024" para sa en_US.

Ang bawat instance ng Locale ay binubuo ng dalawang component: Language (wika — tinutukoy ang mga pangalan ng buwan, araw ng linggo, pagkakasunod-sunod ng salita) at Region (rehiyon — tinutukoy ang format ng numero, pera, kalendaryo). Ang kumbinasyon ng mga component na ito ay naka-encode sa identifier ayon sa BCP 47 standard: ru_RU (Russian, Russia), en_US (English, US), de_DE (German, Germany).

Ayon sa Unicode CLDR (2024), ang listahan ng mga supported locale sa iOS ay lumalampas sa 700 combinations ng wika-rehiyon. Ginagamit ng Foundation ang data mula sa CLDR (Common Locale Data Repository) — ang pinakakumpletong repositoryo ng lokalisasyon data, na sinusuportahan ng Unicode Consortium. Ginagarantiyahan nito ang pagkakapareho ng pag-format sa lahat ng Apple device.

Paano naaapektuhan ng Locale ang pag-format ng petsa at numero?

DateFormatter ay gumagamit ng Locale para pumili ng tamang mga pangalan ng buwan at araw ng linggo, pagtukoy sa pagkakasunud-sunod ng mga component ng petsa (araw/buwan/taon o buwan/araw/taon) at mga separator. Kung walang explicit na pagtukoy ng Locale, ginagamit ng DateFormatter ang locale ng device — ito ay tama para sa UI, ngunit delikado para sa server data kung saan ang format ay dapat na fixed.

NumberFormatter ay gumagamit ng Locale para sa pagtukoy ng decimal separator (kuwit o tuldok), grouping separator (espasyo, kuwit, tuldok) at simbolo ng pera. Ang pagbalewala sa Locale sa pag-parse ng mga numero ay isa sa mga karaniwang sanhi ng bug sa international apps: ang numerong "1,5" ay nangangahulugang "isa at kalahati" para sa ru_RU, ngunit para sa en_US babasahin ito ng number analyzer bilang "lima" pagkatapos ng kuwit.

Mahalaga: Ang Calendar na ginawa sa pamamagitan ng Calendar.current ay nagmamana ng locale ng device. Ang Calendar(identifier: .gregorian) na may explicit na nakatakdang locale — ang inirerekomendang paraan para sa predictable na pag-format. Sa paggamit ng ISO 8601 na mga petsa, palaging gamitin ang Locale(identifier: "en_US_POSIX") — isang espesyal na locale para sa technical formatting na hindi apektado ng regional settings.

Mga Identifier ng Locale: mga pangunahing format

Ang Identifier ng Locale ay binubuo ng language code (ISO 639-1, dalawang character) at region code (ISO 3166-1, dalawang character), na pinaghihiwalay ng underscore. Mga halimbawa: ru_RU, en_US, fr_FR, zh_Hans_CN (Chinese, simplified script, China). Sinusuportahan din ng Foundation ang mga identifier sa BCP 47 format: ru-RU, en-US, na ginagamit sa web standards.

Bukod sa kumpletong identifier, ang Locale ay maaaring gawin batay lamang sa wika: Ang Locale(identifier: "ru") ay nagbabalik ng locale na may Russian at default na rehiyon para sa wikang ito (karaniwang Russia). Katulad para sa English: Ang Locale(identifier: "en") ay gumagamit ng rehiyon ng US. Ang approach na ito ay kapaki-pakinabang para sa pagtatakda ng wika ng pag-format nang walang pagbubuklod sa isang partikular na rehiyon.

Mga espesyal na locale ay kinabibilangan ng en_US_POSIX — isang technical locale para sa machine formatting ng mga petsa at numero, na ginagarantiyahan ang stable na format anuman ang mga setting ng user. Ang locale na ito ay sapilitan para sa pag-parse ng mga petsa mula sa server APIs, lalo na para sa ISO 8601 format. Gumagamit ito ng Gregorian calendar, 24-hour time format at tuldok bilang decimal separator.

import Foundation

// Mga available na identifier ng locale
let available: [String] = Locale.availableIdentifiers
print("Kabuuang locale: \(available.count)")

// I-filter ang Russian locales
let russianLocales = available.filter { $0.hasPrefix("ru") }
print("Russian locales: \(russianLocales)")

// Mga component ng locale
let locale = Locale(identifier: "de_DE")
print("Wika: \(locale.languageCode ?? "nil")")
print("Rehiyon: \(locale.regionCode ?? "nil")")
print("Pera: \(locale.currencyCode ?? "nil")")
print("Kalendaryo: \(locale.calendar.identifier)")

Pagsusuri ng mga available na locale sa pamamagitan ng Locale.availableIdentifiers ay nagbabalik ng array ng lahat ng identifier na sinusuportahan ng kasalukuyang bersyon ng iOS. Para sa pag-filter ayon sa rehiyon, gamitin ang Locale.availableIdentifiers.filter na may pagsusuri ng regionCode. Ito ay kapaki-pakinabang para sa pagbuo ng UI ng pagpili ng rehiyon nang walang hard-coded na listahan.

Pagtukoy sa kasalukuyang locale ng user sa Swift

Locale.current — ang pangunahing paraan upang makuha ang kasalukuyang locale ng device na itinakda ng user sa iOS settings (Settings > General > Language & Region). Ang property na ito ay awtomatikong naa-update kapag binago ang wika o rehiyon sa mga setting nang hindi nirirestart ang app. Gayunpaman, maaaring hindi ito tumugma sa ginustong locale para sa pagpapakita ng content: maaaring itakda ng user ang interface language sa English ngunit tingnan ang mga petsa sa Russian format.

Para sa mas tumpak na pagtukoy sa mga kagustuhan ng user, gamitin ang Locale.preferredLanguages — isang array ng mga wikang pinagsunod-sunod ayon sa priyoridad ng user. Ang unang elemento ay ang pangunahing wika ng interface. Ang listahang ito ay tumutugma sa mga setting sa Language & Region, kabilang ang pag-drag ng mga wika sa pagkakasunud-sunod ng kagustuhan. Ang mga communication app (mga messenger, email client) ay dapat isaalang-alang ang order na ito kapag pumipili ng wika ng pagpapakita ng content.

import Foundation

// Kasalukuyang system locale
let current = Locale.current
print("Kasalukuyang locale: \(current.identifier)")
print("Wika: \(current.language?.disjointName ?? "nil")")

// Mga ginustong wika ng user
let preferred = Locale.preferredLanguages
print("Mga ginustong wika: \(preferred)")

// Kunin ang rehiyon mula sa kasalukuyang locale
if let region = current.regionCode {
    let regionLocale = Locale(identifier: "en_\(region)")
    let countryName = regionLocale.localizedString(
        forRegionCode: region
    )
    print("Bansa: \(countryName ?? region)")
}

// Suriin ang 24h format
let uses24h = current.uses24hClock(
    for: .dateAndTime
)
print("Gumagamit ng 24h: \(uses24h)")

Lokalisasyon sa UI: para sa pagpapakita ng mga pangalan ng buwan at araw ng linggo sa wika ng interface, gamitin ang Calendar na may nakatakdang locale. Ang Calendar.current.symbols(for: .month) ay nagbabalik ng mga pangalan ng buwan sa wika ng kasalukuyang locale. Para sa pagpapakita ng mga pangalan ng bansa sa wika ng user, gamitin ang Locale.current.localizedString(forRegionCode:).

Locale sa Swift: mga halimbawa ng paggamit

Pag-format ng petsa na isinasaalang-alang ang locale — pangunahing gawain sa pagpapakita ng mga petsa sa user. Ang DateFormatter na may nakatakdang locale ay awtomatikong pumipili ng tamang format ng petsa at oras para sa rehiyon ng user. Para sa dateStyle at timeStyle na may mga value na .short, .medium, .long, .full, ginagamit ng formatter ang mga panuntunan ng locale para sa pagbuo ng mga component ng petsa.

import Foundation

let date = Date()

// Pag-format sa iba't ibang locale
let formatter = DateFormatter()
formatter.dateStyle = .medium

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

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

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

// Pag-format ng pera gamit ang locale
let numFormatter = NumberFormatter()
numFormatter.numberStyle = .currency

numFormatter.locale = Locale(identifier: "de_DE")
print("Pera ng Germany: \(numFormatter.string(from: 1234.56) ?? "nil")")

numFormatter.locale = Locale(identifier: "en_US")
print("Pera ng US: \(numFormatter.string(from: 1234.56) ?? "nil")")

Pag-parse ng mga petsa mula sa server APIs ay dapat palaging gumamit ng Locale(identifier: "en_US_POSIX") para sa fixed format. Karaniwang nagpapadala ang mga server ng mga petsa sa ISO 8601 format na may English na mga pangalan ng buwan, at ang paggamit ng kasalukuyang locale ng device ay maaaring magdulot ng parsing error kung ang user ay nasa rehiyon na may non-English na wika. Ginagarantiyahan ng en_US_POSIX na ang pag-parse ay hindi nakadepende sa mga setting ng device.

import Foundation

// Tamang pag-parse ng server dates
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("Na-parse na petsa: \(parsed)")
}

// Lokalisadong pangalan ng pera
let usLocale = Locale(identifier: "en_US")
let currencyName = usLocale.localizedString(
    forCurrencyCode: "RUB"
)
print("Russian ruble sa US locale: \(currencyName ?? "nil")")

Mga karagdagang kakayahan: Ang Locale ay nagbibigay ng lokalisadong paglalarawan ng mga component nito sa pamamagitan ng mga pamamaraang localizedString(forRegionCode:), localizedString(forLanguageCode:), localizedString(forCurrencyCode:) at localizedString(forCalendarIdentifier:). Ang mga pamamaraang ito ay nagbabalik ng mga pangalan sa wika ng locale kung saan sila tinawag. Halimbawa, ang Locale(identifier: "ru_RU").localizedString(forCountryCode: "DE") ay magbabalik ng "Germany".

Mga karaniwang pagkakamali sa paggamit ng Locale

Pagbalewala sa Locale kapag nagpa-parse ng mga numero — isang kritikal na pagkakamali sa international apps. Ang NumberFormatter na walang explicit na locale ay gumagamit ng kasalukuyang locale ng device. Kung ang user sa Russia ay nag-input ng "1,5", ang NumberFormatter.number(from: "1,5") ay wastong nagbabalik ng 1.5. Ngunit kung ang parehong code ay isasagawa sa isang device na may en_US locale, ang pag-parse ay magbabalik ng nil, dahil para sa en_US ang decimal separator ay tuldok.

Kawalan ng en_US_POSIX para sa server dates ay humahantong sa mahirap na matukoy na mga bug. Ang DateFormatter na may dateFormat at locale = Locale.current ay maaaring masira sa mga user mula sa mga rehiyon kung saan ang format ng petsa ay naiiba sa American. Halimbawa, sa Germany ang DateFormatter ay maaaring umasa ng "21.07.2024" habang ang server ay nagpapadala ng "07/21/2024". Ginagarantiyahan ng en_US_POSIX ang fixed format para sa machine parsing anuman ang rehiyon ng user.

Paghahambing ng mga string ng petsa sa halip na paggamit ng Date — isa pang karaniwang pagkakamali. Minsan inihahambing ng mga developer ang string representations ng mga petsa mula sa iba't ibang locale, na nakakakuha ng maling resulta. Binabago lamang ng Locale ang display, hindi ang absolute value ng petsa. Palaging ihambing ang mga Date object, hindi ang kanilang string representations. Para sa paghahambing ng mga component ng petsa, gamitin ang Calendar na may explicit na nakatakdang locale.

Ayon sa WWDC 2023, humigit-kumulang 30% ng mga problema sa internationalisasyon sa mga app ay nauugnay sa maling configuration ng Locale. Inirerekomenda ng Apple na palaging itakda nang explicit ang locale para sa DateFormatter at NumberFormatter kapag nagtatrabaho sa server data at gamitin lamang ang Locale.current para sa pagpapakita sa UI. Ang simpleng practice na ito ay nag-aalis ng karamihan sa mga bug na nauugnay sa regional settings.