From a6664573c1d3ac78515332afd7a6a7eb37b83f06 Mon Sep 17 00:00:00 2001 From: Nicola Pero Date: Fri, 31 Aug 2001 11:01:14 +0000 Subject: [PATCH] Documented the localization functions/macros git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@10821 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 7 + Documentation/gsdoc/NSFunctions.gsdoc | 245 ++++++++++++++++++++++ Documentation/gsdoc/NSFunctions.html | 286 +++++++++++++++++++++++++- 3 files changed, 537 insertions(+), 1 deletion(-) diff --git a/ChangeLog b/ChangeLog index a1714a0e8..4b1f58209 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Fri Aug 31 11:58:42 2001 Nicola Pero + + * Documentation/gsdoc/NSFunctions.gsdoc: Documented the + localization functions/macros: NSLocalizedString, + NSLocalizedStringFromTable, NSLocalizedStringFromTableInBundle, + NSLocalizedStaticString, _ and __. + 2001-08-30 Adam Fedor * Tools/sfparse.m: Add code to convert files to Unicode. diff --git a/Documentation/gsdoc/NSFunctions.gsdoc b/Documentation/gsdoc/NSFunctions.gsdoc index fee7de1ec..f572717ce 100644 --- a/Documentation/gsdoc/NSFunctions.gsdoc +++ b/Documentation/gsdoc/NSFunctions.gsdoc @@ -267,6 +267,251 @@ + +
+ Localization Functions and Macros + + key + comment + Foundation/NSBundle.h + +

+ This function (macro) is used to get the localized + translation of the string key. + key is looked up in the + Localizable.strings file for the current + language. The current language is determined by the + available languages in which the application is + translated, and by using the NSLanguages user + defaults (which should contain an array of the languages + preferred by the user, in order of preference). +

+

+ Technically, the function works by calling + localizedStringForKey:value:table: on the + main bundle, using @"" as value, and + nil as the table. The comment + is ignored when the macro is expanded; but when we have + tools which can generate the + Localizable.strings files automatically from + source code, the comment will be used by the + tools and added as a comment before the string to + translate. Upon finding something like +

+

+ + NSLocalizedString (@"My useful string", + @"My useful comment about the string"); + +

+

+ in the source code, the tools will generate the lines +

+

+ + /* My useful comment about the string */ + " My useful string" = "My useful string"; + +

+

+ in the Localizable.strings file (the + translator then can use this as a skeleton for the + Localizable.strings for his/her own language, + where she/he can replace the right hand side with the + translation in her/his own language). The comment can + help the translator to decide how to translate when it is + not clear how to translate (because the original string is + now out of context, and out of context might not be so + clear what the string means). The comment is totally + ignored by the library code. +

+

+ If you don't have a comment (because the string is so + self-explanatory that it doesn't need it), you can leave + it blank, by using @"" as a comment. If the + string might be unclear out of context, it is recommended + that you add a comment (even if it is unused for now). +

+ + + + key + table + comment + Foundation/NSBundle.h + +

+ This function (macro) does the same as + NSLocalizedString, but uses the table + table rather than the default table. This + means that the string to translate will be looked up in a + different file than Localizable.strings. For + example, if you pass DatabaseErrors as the + table, the string will be looked up for + translation in the file + DatabaseErrors.strings. This allows you to + have the same string translated in different ways, by + having a different translation in different tables, and + choosing between the different translation by choosing a + different table. +

+ + + + key + table + bundle + comment + Foundation/NSBundle.h + +

+ This function is the full-blown localization function (it + is actually a macro). It looks up the string + key for translation in the table + table of the bundle bundle + (please refer to the NSBundle documentation for more + information on how this lookup is done). + comment is a comment, which is ignored by the + library (it is discarded when the macro is expanded) but which + can be used by tools which parse the source code and generate + strings table to provide a comment which the translator can + use when translating the string. +

+ + +
+
+ GNUstep Localization Functions and Macros + + key + comment + Foundation/NSBundle.h + +

+ This function (macro) is a GNUstep extensions, and it is used + to localize static strings. Here is an example of a static + string: +

+

+ + NSString *message = @"Hi there"; + + /* ... some code ... */ + + NSLog (message); + +

+

+ This string can not be localized using the standard + openstep functions/macros. By using this gnustep extension, + you can localize it as follows: +

+

+ + NSString *message = NSLocalizedStaticString (@"Hi there", + @"Greeting"); + + /* ... some code ... */ + + NSLog (NSLocalizedString (message, @"")); + +

+

+ When the tools generate the + Localizable.strings file from the source + code, they will ignore the NSLocalizedString + call while they will extract the string (and the comment) + to localize from the NSLocalizedStaticString + call. +

+

+ When the code is compiled, instead, the + NSLocalizedStaticString call is ignored (discarded, + it is a macro which simply expands to key), while + the NSLocalizedString will actually look up the + string for translation in the Localizable.strings + file. +

+

+ Please note that there is currently no macro/function to + localize static strings using different tables. If you + need that functionality, you have either to prepare the + localization tables by hand, or to rewrite your code in + such a way as not to use static strings. +

+ + + + + key + Foundation/NSBundle.h + +

+ This function (macro) is a GNUstep extension. +

+

+ _(@"My string to translate") +

+

+ is exactly the same as +

+

+ NSLocalizedString (@"My string to translate", @"") +

+

+ It is useful when you need to translate an application + very quickly, as you just need to enclose all strings + inside _(). But please note that when you + use this macro, you are not taking advantage of comments + for the translator, so consider using + NSLocalizedString instead when you need a + comment. +

+ + + + + + key + Foundation/NSBundle.h + +

+ This function (macro) is a GNUstep extension. +

+

+ __(@"My string to translate") +

+

+ is exactly the same as +

+

+ NSLocalizedStaticString (@"My string to translate", + @"") +

+

+ It is useful when you need to translate an application very + quickly. You would use it as follows for static strings: +

+

+ + NSString *message = __(@"Hello there"); + + /* ... more code ... */ + + NSLog (_(messages)); + +

+

+ But please note that when you use this macro, you are not + taking advantage of comments for the translator, so + consider using NSLocalizedStaticString + instead when you need a comment. +

+ + + + +
diff --git a/Documentation/gsdoc/NSFunctions.html b/Documentation/gsdoc/NSFunctions.html index 6fa6f67c4..354692e60 100644 --- a/Documentation/gsdoc/NSFunctions.html +++ b/Documentation/gsdoc/NSFunctions.html @@ -276,7 +276,291 @@
-

Types

+

Localization Functions and Macros

+

NSLocalizedString

+

Declared in: Foundation/NSBundle.h

+Prototype: NSString * NSLocalizedString(NSString * key, NSString * comment)
+ +

+ + This function (macro) is used to get the localized + translation of the string key. + key is looked up in the + Localizable.strings file for the current + language. The current language is determined by the + available languages in which the application is + translated, and by using the NSLanguages user + defaults (which should contain an array of the languages + preferred by the user, in order of preference). +

+ +

+ + Technically, the function works by calling + localizedStringForKey:value:table: on the + main bundle, using @"" as value, and + nil as the table. The comment + is ignored when the macro is expanded; but when we have + tools which can generate the + Localizable.strings files automatically from + source code, the comment will be used by the + tools and added as a comment before the string to + translate. Upon finding something like +

+ +

+ + + NSLocalizedString (@"My useful string", + @"My useful comment about the string"); + +

+ +

+ + in the source code, the tools will generate the lines +

+ +

+ + + /* My useful comment about the string */ + " My useful string" = "My useful string"; + +

+ +

+ + in the Localizable.strings file (the + translator then can use this as a skeleton for the + Localizable.strings for his/her own language, + where she/he can replace the right hand side with the + translation in her/his own language). The comment can + help the translator to decide how to translate when it is + not clear how to translate (because the original string is + now out of context, and out of context might not be so + clear what the string means). The comment is totally + ignored by the library code. +

+ +

+ + If you don't have a comment (because the string is so + self-explanatory that it doesn't need it), you can leave + it blank, by using @"" as a comment. If the + string might be unclear out of context, it is recommended + that you add a comment (even if it is unused for now). +

+ + +
+

NSLocalizedStringFromTable

+

Declared in: Foundation/NSBundle.h

+Prototype: NSString * NSLocalizedStringFromTable(NSString * key, NSString * table, NSString * comment)
+ +

+ + This function (macro) does the same as + NSLocalizedString, but uses the table + table rather than the default table. This + means that the string to translate will be looked up in a + different file than Localizable.strings. For + example, if you pass DatabaseErrors as the + table, the string will be looked up for + translation in the file + DatabaseErrors.strings. This allows you to + have the same string translated in different ways, by + having a different translation in different tables, and + choosing between the different translation by choosing a + different table. +

+ + +
+

NSLocalizedStringFromTableInBundle

+

Declared in: Foundation/NSBundle.h

+Prototype: NSString * NSLocalizedStringFromTableInBundle(NSString * key, NSString * table, NSString * bundle, NSString * comment)
+ +

+ + This function is the full-blown localization function (it + is actually a macro). It looks up the string + key for translation in the table + table of the bundle bundle + (please refer to the NSBundle documentation for more + information on how this lookup is done). + comment is a comment, which is ignored by the + library (it is discarded when the macro is expanded) but which + can be used by tools which parse the source code and generate + strings table to provide a comment which the translator can + use when translating the string. +

+ + +
+

GNUstep Localization Functions and Macros

+

NSLocalizedStaticString

+

Declared in: Foundation/NSBundle.h

+Prototype: NSString * NSLocalizedStaticString(NSString * key, NSString * comment)
+ +

+ + This function (macro) is a GNUstep extensions, and it is used + to localize static strings. Here is an example of a static + string: +

+ +

+ + + NSString *message = @"Hi there"; + + /* ... some code ... */ + + NSLog (message); + +

+ +

+ + This string can not be localized using the standard + openstep functions/macros. By using this gnustep extension, + you can localize it as follows: +

+ +

+ + + NSString *message = NSLocalizedStaticString (@"Hi there", + @"Greeting"); + + /* ... some code ... */ + + NSLog (NSLocalizedString (message, @"")); + +

+ +

+ + When the tools generate the + Localizable.strings file from the source + code, they will ignore the NSLocalizedString + call while they will extract the string (and the comment) + to localize from the NSLocalizedStaticString + call. +

+ +

+ + When the code is compiled, instead, the + NSLocalizedStaticString call is ignored (discarded, + it is a macro which simply expands to key), while + the NSLocalizedString will actually look up the + string for translation in the Localizable.strings + file. +

+ +

+ + Please note that there is currently no macro/function to + localize static strings using different tables. If you + need that functionality, you have either to prepare the + localization tables by hand, or to rewrite your code in + such a way as not to use static strings. +

+ + +
+

_

+

Declared in: Foundation/NSBundle.h

+Prototype: NSString * _(NSString * key)
+ +

+ + This function (macro) is a GNUstep extension. +

+ +

+ + _(@"My string to translate") +

+ +

+ + is exactly the same as +

+ +

+ + NSLocalizedString (@"My string to translate", @"") +

+ +

+ + It is useful when you need to translate an application + very quickly, as you just need to enclose all strings + inside _(). But please note that when you + use this macro, you are not taking advantage of comments + for the translator, so consider using + NSLocalizedString instead when you need a + comment. +

+ + +
+

__

+

Declared in: Foundation/NSBundle.h

+Prototype: NSString * __(NSString * key)
+ +

+ + This function (macro) is a GNUstep extension. +

+ +

+ + __(@"My string to translate") +

+ +

+ + is exactly the same as +

+ +

+ + NSLocalizedStaticString (@"My string to translate", + @"") +

+ +

+ + It is useful when you need to translate an application very + quickly. You would use it as follows for static strings: +

+ +

+ + + NSString *message = __(@"Hello there"); + + /* ... more code ... */ + + NSLog (_(messages)); + +

+ +

+ + But please note that when you use this macro, you are not + taking advantage of comments for the translator, so + consider using NSLocalizedStaticString + instead when you need a comment. +

+ + +
+

Types

NSRange

Declared in: Foundation/NSRange.h

typedef