Artifact 11147ec8933f0a7de65f8bb83cc33253859061e9186cd039d4dcf254a4fb420b:
- File
src/OFLocale.h
— part of check-in
[88ed5be671]
at
2022-11-23 21:39:13
on branch trunk
— Use a URI for the localization directory
This theoretically allows embedding localizations. While this isn't
great as all will be held in memory but only one will be used, there
might be cases where everything should be in one binary. (user: js, size: 7097) [annotate] [blame] [check-ins using]
/* * Copyright (c) 2008-2022 Jonathan Schleifer <js@nil.im> * * All rights reserved. * * This file is part of ObjFW. It may be distributed under the terms of the * Q Public License 1.0, which can be found in the file LICENSE.QPL included in * the packaging of this file. * * Alternatively, it may be distributed under the terms of the GNU General * Public License, either version 2 or 3, which can be found in the file * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this * file. */ #import "OFObject.h" #import "OFString.h" OF_ASSUME_NONNULL_BEGIN @class OFURI; /** @file */ /** * @def OF_LOCALIZED * * @brief Returns the localized string for the specified ID with the specified * arguments inserted. * * @param ID The ID of the localized string to retrieve * @return The localized string with the specified arguments replaced * @throw OFInvalidFormatException The string (either the fallback or the * localized one) contains an invalid format */ #define OF_LOCALIZED(ID, ...) \ [[OFLocale currentLocale] localizedStringForID: ID \ fallback: __VA_ARGS__, nil] @class OFMutableArray OF_GENERIC(ObjectType); @class OFDictionary OF_GENERIC(KeyType, ObjectType); /** * @class OFLocale OFLocale.h ObjFW/OFLocale.h * * @brief A class for querying the locale and retrieving localized strings. */ OF_SUBCLASSING_RESTRICTED @interface OFLocale: OFObject { OFString *_Nullable _languageCode, *_Nullable _countryCode; OFStringEncoding _encoding; OFString *_decimalSeparator; OFMutableArray OF_GENERIC(OFDictionary OF_GENERIC(OFString *, id) *) *_localizedStrings; } #ifdef OF_HAVE_CLASS_PROPERTIES @property (class, readonly, nullable, nonatomic) OFLocale *currentLocale; @property (class, readonly, nullable, nonatomic) OFString *languageCode; @property (class, readonly, nullable, nonatomic) OFString *countryCode; @property (class, readonly, nonatomic) OFStringEncoding encoding; @property (class, readonly, nullable, nonatomic) OFString *decimalSeparator; #endif /** * @brief The language code of the locale for messages. * * If the language is unknown, it is `nil`. */ @property OF_NULLABLE_PROPERTY (readonly, nonatomic) OFString *languageCode; /** * @brief The country code of the locale for messages. * * If the territory is unknown, it is `nil`. */ @property OF_NULLABLE_PROPERTY (readonly, nonatomic) OFString *countryCode; /** * @brief The native 8-bit string encoding of the locale for messages. * * This is useful to encode strings correctly for passing them to operating * system calls. * * If the native 8-bit encoding is unknown, UTF-8 is assumed. */ @property (readonly, nonatomic) OFStringEncoding encoding; /** * @brief The decimal separator of the locale. */ @property (readonly, nonatomic) OFString *decimalSeparator; /** * @brief Returns the current OFLocale. * * @warning If you don't use @ref OFApplication, this might be `nil`! In this * case, you need to manually allocate an instance and call * @ref init once. * * @return The current OFLocale instance */ + (nullable OFLocale *)currentLocale; /** * @brief Returns the language code of the locale. * * If the language is unknown, `nil` is returned. * * @return The language code of the locale. */ + (nullable OFString *)languageCode; /** * @brief Returns the country code of the locale. * * If the country is unknown, `nil` is returned. * * @return The country code of the locale. */ + (nullable OFString *)countryCode; /** * @brief Returns the native 8-bit string encoding for the locale. * * This is useful to encode strings correctly for passing them to operating * system calls. * * If the native 8-bit encoding is unknown, UTF-8 is assumed. * * @return The native 8-bit string encoding for the locale */ + (OFStringEncoding)encoding; /** * @brief Returns the decimal point of the system's locale. * * @return The decimal point of the system's locale */ + (nullable OFString *)decimalSeparator; /** * @brief Adds a directory to scan for localizations. * * @param URI The URI to the directory to scan for localizations */ + (void)addLocalizationDirectoryURI: (OFURI *)URI; /** * @brief Initializes the current OFLocale. * * @warning This sets the locale via `setlocale()`! * * @warning You should never call this yourself, except if you do not use * @ref OFApplication. In this case, you need to allocate exactly one * instance of OFLocale, which will become the current locale, and * call this method. */ - (instancetype)init; /** * @brief Adds a directory to scan for localizations. * * @param URI The URI to the directory to scan for localizations */ - (void)addLocalizationDirectoryURI: (OFURI *)URI; /** * @brief Returns the localized string for the specified ID, using the fallback * string if it cannot be looked up or is missing. * * @note This takes a variadic argument, terminated by `nil`, that consists of * pairs of variable names and variable values, which will be replaced * inside the localized string. For example, you can pass * `@"name", @"foo", nil`, causing `%[name]` to be replaced with `foo` in * the localized string. * * @note Generally, you want to use @ref OF_LOCALIZED instead, which also takes * care of the `nil` sentinel automatically. * * @param ID The ID for the localized string * @param fallback The fallback to use in case the localized string cannot be * looked up or is missing. This can also be an array and use * plural scripting, just like with the JSON localization files. * @return The localized string */ - (OFString *)localizedStringForID: (OFConstantString *)ID fallback: (id)fallback, ... OF_SENTINEL; /** * @brief Returns the localized string for the specified ID, using the fallback * string if it cannot be looked up or is missing. * * @note This takes a variadic argument, terminated by `nil` and passed as * va_list, that consists of pairs of variable names and variable values, * which will be replaced inside the localized string. For example, you * can pass `@"name", @"foo", nil`, causing `%[name]` to be replaced with * `foo` in the localized string. * * @note Generally, you want to use @ref OF_LOCALIZED instead, which also takes * care of the `nil` sentinel automatically. * * @param ID The ID for the localized string * @param fallback The fallback to use in case the localized string cannot be * looked up or is missing. This can also be an array and use * plural scripting, just like with the JSON localization files. * @param arguments A va_list of arguments, consisting of pairs of variable * names and values to replace in the localized string, * terminated with `nil` * @return The localized string * @throw OFInvalidFormatException The string (either the fallback or the * localized one) contains an invalid format */ - (OFString *)localizedStringForID: (OFConstantString *)ID fallback: (id)fallback arguments: (va_list)arguments; @end OF_ASSUME_NONNULL_END