mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-23 00:41:02 +00:00
Documented the localization functions/macros
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@10821 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
nico
parent
5506adf3eb
commit
a2be53c7d0
3 changed files with 537 additions and 1 deletions
|
|
@ -1,3 +1,10 @@
|
|||
Fri Aug 31 11:58:42 2001 Nicola Pero <nicola@brainstorm.co.uk>
|
||||
|
||||
* Documentation/gsdoc/NSFunctions.gsdoc: Documented the
|
||||
localization functions/macros: NSLocalizedString,
|
||||
NSLocalizedStringFromTable, NSLocalizedStringFromTableInBundle,
|
||||
NSLocalizedStaticString, _ and __.
|
||||
|
||||
2001-08-30 Adam Fedor <fedor@gnu.org>
|
||||
|
||||
* Tools/sfparse.m: Add code to convert files to Unicode.
|
||||
|
|
|
|||
|
|
@ -267,6 +267,251 @@
|
|||
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||
</function>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<heading>Localization Functions and Macros</heading>
|
||||
<function name="NSLocalizedString" type="NSString *">
|
||||
<arg type="NSString *">key</arg>
|
||||
<arg type="NSString *">comment</arg>
|
||||
<declared>Foundation/NSBundle.h</declared>
|
||||
<desc>
|
||||
<p>
|
||||
This function (macro) is used to get the localized
|
||||
translation of the string <code>key</code>.
|
||||
<code>key</code> is looked up in the
|
||||
<code>Localizable.strings</code> file for the current
|
||||
language. The current language is determined by the
|
||||
available languages in which the application is
|
||||
translated, and by using the <code>NSLanguages</code> user
|
||||
defaults (which should contain an array of the languages
|
||||
preferred by the user, in order of preference).
|
||||
</p>
|
||||
<p>
|
||||
Technically, the function works by calling
|
||||
<code>localizedStringForKey:value:table:</code> on the
|
||||
main bundle, using <code>@""</code> as value, and
|
||||
<code>nil</code> as the table. The <code>comment</code>
|
||||
is ignored when the macro is expanded; but when we have
|
||||
tools which can generate the
|
||||
<code>Localizable.strings</code> files automatically from
|
||||
source code, the <code>comment</code> will be used by the
|
||||
tools and added as a comment before the string to
|
||||
translate. Upon finding something like
|
||||
</p>
|
||||
<p>
|
||||
<code>
|
||||
NSLocalizedString (@"My useful string",
|
||||
@"My useful comment about the string");
|
||||
</code>
|
||||
</p>
|
||||
<p>
|
||||
in the source code, the tools will generate the lines
|
||||
</p>
|
||||
<p>
|
||||
<code>
|
||||
/* My useful comment about the string */
|
||||
" My useful string" = "My useful string";
|
||||
</code>
|
||||
</p>
|
||||
<p>
|
||||
in the <code>Localizable.strings</code> file (the
|
||||
translator then can use this as a skeleton for the
|
||||
<code>Localizable.strings</code> 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.
|
||||
</p>
|
||||
<p>
|
||||
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 <code>@""</code> 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).
|
||||
</p>
|
||||
</desc>
|
||||
</function>
|
||||
<function name="NSLocalizedStringFromTable" type="NSString *">
|
||||
<arg type="NSString *">key</arg>
|
||||
<arg type="NSString *">table</arg>
|
||||
<arg type="NSString *">comment</arg>
|
||||
<declared>Foundation/NSBundle.h</declared>
|
||||
<desc>
|
||||
<p>
|
||||
This function (macro) does the same as
|
||||
<code>NSLocalizedString</code>, but uses the table
|
||||
<code>table</code> rather than the default table. This
|
||||
means that the string to translate will be looked up in a
|
||||
different file than <code>Localizable.strings</code>. For
|
||||
example, if you pass <code>DatabaseErrors</code> as the
|
||||
<code>table</code>, the string will be looked up for
|
||||
translation in the file
|
||||
<code>DatabaseErrors.strings</code>. 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.
|
||||
</p>
|
||||
</desc>
|
||||
</function>
|
||||
<function name="NSLocalizedStringFromTableInBundle" type="NSString *">
|
||||
<arg type="NSString *">key</arg>
|
||||
<arg type="NSString *">table</arg>
|
||||
<arg type="NSString *">bundle</arg>
|
||||
<arg type="NSString *">comment</arg>
|
||||
<declared>Foundation/NSBundle.h</declared>
|
||||
<desc>
|
||||
<p>
|
||||
This function is the full-blown localization function (it
|
||||
is actually a macro). It looks up the string
|
||||
<code>key</code> for translation in the table
|
||||
<code>table</code> of the bundle <code>bundle</code>
|
||||
(please refer to the NSBundle documentation for more
|
||||
information on how this lookup is done).
|
||||
<code>comment</code> 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.
|
||||
</p>
|
||||
</desc>
|
||||
</function>
|
||||
</section>
|
||||
<section>
|
||||
<heading>GNUstep Localization Functions and Macros</heading>
|
||||
<function name="NSLocalizedStaticString" type="NSString *">
|
||||
<arg type="NSString *">key</arg>
|
||||
<arg type="NSString *">comment</arg>
|
||||
<declared>Foundation/NSBundle.h</declared>
|
||||
<desc>
|
||||
<p>
|
||||
This function (macro) is a GNUstep extensions, and it is used
|
||||
to localize static strings. Here is an example of a static
|
||||
string:
|
||||
</p>
|
||||
<p>
|
||||
<code>
|
||||
NSString *message = @"Hi there";
|
||||
|
||||
/* ... some code ... */
|
||||
|
||||
NSLog (message);
|
||||
</code>
|
||||
</p>
|
||||
<p>
|
||||
This string can not be localized using the standard
|
||||
openstep functions/macros. By using this gnustep extension,
|
||||
you can localize it as follows:
|
||||
</p>
|
||||
<p>
|
||||
<code>
|
||||
NSString *message = NSLocalizedStaticString (@"Hi there",
|
||||
@"Greeting");
|
||||
|
||||
/* ... some code ... */
|
||||
|
||||
NSLog (NSLocalizedString (message, @""));
|
||||
</code>
|
||||
</p>
|
||||
<p>
|
||||
When the tools generate the
|
||||
<code>Localizable.strings</code> file from the source
|
||||
code, they will ignore the <code>NSLocalizedString</code>
|
||||
call while they will extract the string (and the comment)
|
||||
to localize from the <code>NSLocalizedStaticString</code>
|
||||
call.
|
||||
</p>
|
||||
<p>
|
||||
When the code is compiled, instead, the
|
||||
<code>NSLocalizedStaticString</code> call is ignored (discarded,
|
||||
it is a macro which simply expands to <code>key</code>), while
|
||||
the <code>NSLocalizedString</code> will actually look up the
|
||||
string for translation in the <code>Localizable.strings</code>
|
||||
file.
|
||||
</p>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</desc>
|
||||
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||
</function>
|
||||
<function name="_" type="NSString *">
|
||||
<arg type="NSString *">key</arg>
|
||||
<declared>Foundation/NSBundle.h</declared>
|
||||
<desc>
|
||||
<p>
|
||||
This function (macro) is a GNUstep extension.
|
||||
</p>
|
||||
<p>
|
||||
<code>_(@"My string to translate")</code>
|
||||
</p>
|
||||
<p>
|
||||
is exactly the same as
|
||||
</p>
|
||||
<p>
|
||||
<code>NSLocalizedString (@"My string to translate", @"")</code>
|
||||
</p>
|
||||
<p>
|
||||
It is useful when you need to translate an application
|
||||
very quickly, as you just need to enclose all strings
|
||||
inside <code>_()</code>. But please note that when you
|
||||
use this macro, you are not taking advantage of comments
|
||||
for the translator, so consider using
|
||||
<code>NSLocalizedString</code> instead when you need a
|
||||
comment.
|
||||
</p>
|
||||
</desc>
|
||||
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||
</function>
|
||||
|
||||
<function name="__" type="NSString *">
|
||||
<arg type="NSString *">key</arg>
|
||||
<declared>Foundation/NSBundle.h</declared>
|
||||
<desc>
|
||||
<p>
|
||||
This function (macro) is a GNUstep extension.
|
||||
</p>
|
||||
<p>
|
||||
<code>__(@"My string to translate")</code>
|
||||
</p>
|
||||
<p>
|
||||
is exactly the same as
|
||||
</p>
|
||||
<p>
|
||||
<code>NSLocalizedStaticString (@"My string to translate",
|
||||
@"")</code>
|
||||
</p>
|
||||
<p>
|
||||
It is useful when you need to translate an application very
|
||||
quickly. You would use it as follows for static strings:
|
||||
</p>
|
||||
<p>
|
||||
<code>
|
||||
NSString *message = __(@"Hello there");
|
||||
|
||||
/* ... more code ... */
|
||||
|
||||
NSLog (_(messages));
|
||||
</code>
|
||||
</p>
|
||||
<p>
|
||||
But please note that when you use this macro, you are not
|
||||
taking advantage of comments for the translator, so
|
||||
consider using <code>NSLocalizedStaticString</code>
|
||||
instead when you need a comment.
|
||||
</p>
|
||||
</desc>
|
||||
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||
</function>
|
||||
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
|
|
|
|||
|
|
@ -276,7 +276,291 @@
|
|||
|
||||
|
||||
<hr>
|
||||
<h2><a name ="cont-4">Types</a></h2>
|
||||
<h3><a name ="cont-4">Localization Functions and Macros</a></h3>
|
||||
<h2><a name ="function-12">NSLocalizedString</a></h2>
|
||||
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
||||
<b>Prototype: </b> NSString * NSLocalizedString(NSString * key, NSString * comment)<br>
|
||||
|
||||
<p>
|
||||
|
||||
This function (macro) is used to get the localized
|
||||
translation of the string <code>key</code>.
|
||||
<code>key</code> is looked up in the
|
||||
<code>Localizable.strings</code> file for the current
|
||||
language. The current language is determined by the
|
||||
available languages in which the application is
|
||||
translated, and by using the <code>NSLanguages</code> user
|
||||
defaults (which should contain an array of the languages
|
||||
preferred by the user, in order of preference).
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
Technically, the function works by calling
|
||||
<code>localizedStringForKey:value:table:</code> on the
|
||||
main bundle, using <code>@""</code> as value, and
|
||||
<code>nil</code> as the table. The <code>comment</code>
|
||||
is ignored when the macro is expanded; but when we have
|
||||
tools which can generate the
|
||||
<code>Localizable.strings</code> files automatically from
|
||||
source code, the <code>comment</code> will be used by the
|
||||
tools and added as a comment before the string to
|
||||
translate. Upon finding something like
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
<code>
|
||||
NSLocalizedString (@"My useful string",
|
||||
@"My useful comment about the string");
|
||||
</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
in the source code, the tools will generate the lines
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
<code>
|
||||
/* My useful comment about the string */
|
||||
" My useful string" = "My useful string";
|
||||
</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
in the <code>Localizable.strings</code> file (the
|
||||
translator then can use this as a skeleton for the
|
||||
<code>Localizable.strings</code> 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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
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 <code>@""</code> 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).
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name ="function-13">NSLocalizedStringFromTable</a></h2>
|
||||
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
||||
<b>Prototype: </b> NSString * NSLocalizedStringFromTable(NSString * key, NSString * table, NSString * comment)<br>
|
||||
|
||||
<p>
|
||||
|
||||
This function (macro) does the same as
|
||||
<code>NSLocalizedString</code>, but uses the table
|
||||
<code>table</code> rather than the default table. This
|
||||
means that the string to translate will be looked up in a
|
||||
different file than <code>Localizable.strings</code>. For
|
||||
example, if you pass <code>DatabaseErrors</code> as the
|
||||
<code>table</code>, the string will be looked up for
|
||||
translation in the file
|
||||
<code>DatabaseErrors.strings</code>. 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.
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name ="function-14">NSLocalizedStringFromTableInBundle</a></h2>
|
||||
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
||||
<b>Prototype: </b> NSString * NSLocalizedStringFromTableInBundle(NSString * key, NSString * table, NSString * bundle, NSString * comment)<br>
|
||||
|
||||
<p>
|
||||
|
||||
This function is the full-blown localization function (it
|
||||
is actually a macro). It looks up the string
|
||||
<code>key</code> for translation in the table
|
||||
<code>table</code> of the bundle <code>bundle</code>
|
||||
(please refer to the NSBundle documentation for more
|
||||
information on how this lookup is done).
|
||||
<code>comment</code> 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.
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<h3><a name ="cont-5">GNUstep Localization Functions and Macros</a></h3>
|
||||
<h2><a name ="function-15">NSLocalizedStaticString</a></h2>
|
||||
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
||||
<b>Prototype: </b> NSString * NSLocalizedStaticString(NSString * key, NSString * comment)<br>
|
||||
|
||||
<p>
|
||||
|
||||
This function (macro) is a GNUstep extensions, and it is used
|
||||
to localize static strings. Here is an example of a static
|
||||
string:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
<code>
|
||||
NSString *message = @"Hi there";
|
||||
|
||||
/* ... some code ... */
|
||||
|
||||
NSLog (message);
|
||||
</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
This string can not be localized using the standard
|
||||
openstep functions/macros. By using this gnustep extension,
|
||||
you can localize it as follows:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
<code>
|
||||
NSString *message = NSLocalizedStaticString (@"Hi there",
|
||||
@"Greeting");
|
||||
|
||||
/* ... some code ... */
|
||||
|
||||
NSLog (NSLocalizedString (message, @""));
|
||||
</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
When the tools generate the
|
||||
<code>Localizable.strings</code> file from the source
|
||||
code, they will ignore the <code>NSLocalizedString</code>
|
||||
call while they will extract the string (and the comment)
|
||||
to localize from the <code>NSLocalizedStaticString</code>
|
||||
call.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
When the code is compiled, instead, the
|
||||
<code>NSLocalizedStaticString</code> call is ignored (discarded,
|
||||
it is a macro which simply expands to <code>key</code>), while
|
||||
the <code>NSLocalizedString</code> will actually look up the
|
||||
string for translation in the <code>Localizable.strings</code>
|
||||
file.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
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.
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name ="function-16">_</a></h2>
|
||||
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
||||
<b>Prototype: </b> NSString * _(NSString * key)<br>
|
||||
|
||||
<p>
|
||||
|
||||
This function (macro) is a GNUstep extension.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
<code>_(@"My string to translate")</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
is exactly the same as
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
<code>NSLocalizedString (@"My string to translate", @"")</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
It is useful when you need to translate an application
|
||||
very quickly, as you just need to enclose all strings
|
||||
inside <code>_()</code>. But please note that when you
|
||||
use this macro, you are not taking advantage of comments
|
||||
for the translator, so consider using
|
||||
<code>NSLocalizedString</code> instead when you need a
|
||||
comment.
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name ="function-17">__</a></h2>
|
||||
<p><b>Declared in: </b> Foundation/NSBundle.h</p>
|
||||
<b>Prototype: </b> NSString * __(NSString * key)<br>
|
||||
|
||||
<p>
|
||||
|
||||
This function (macro) is a GNUstep extension.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
<code>__(@"My string to translate")</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
is exactly the same as
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
<code>NSLocalizedStaticString (@"My string to translate",
|
||||
@"")</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
It is useful when you need to translate an application very
|
||||
quickly. You would use it as follows for static strings:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
<code>
|
||||
NSString *message = __(@"Hello there");
|
||||
|
||||
/* ... more code ... */
|
||||
|
||||
NSLog (_(messages));
|
||||
</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
||||
But please note that when you use this macro, you are not
|
||||
taking advantage of comments for the translator, so
|
||||
consider using <code>NSLocalizedStaticString</code>
|
||||
instead when you need a comment.
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name ="cont-6">Types</a></h2>
|
||||
<h3><a name ="NSRange">NSRange</a></h3>
|
||||
<p><b>Declared in: </b> Foundation/NSRange.h</p>
|
||||
<b>typedef </b>
|
||||
|
|
|
|||
Loading…
Reference in a new issue