head	1.1;
access;
symbols;
locks; strict;
comment	@# @;


1.1
date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
branches;
next	;


desc
@new-topic
@


1.1
log
@buildrelease
@
text
@---+ Package =TWiki::I18N=

Support for strings translation and language detection.


%TOC%

---++ ClassMethod *available_languages* <tt></tt>

Lists languages tags for languages available at TWiki installation. Returns a
list containing the tags of the available languages.

__Note__: the languages available to users are determined in the =configure=
interface.



---++ ClassMethod *get* <tt>($session)</tt>

Constructor. Gets the language object corresponding to the current user's language.



---++ ObjectMethod *maketext* <tt>($text) -> $translation</tt>

Translates the given string (assumed to be written in English) into the
current language, as detected in the constructor, and converts it into
the site charset.

Wraps around Locale::Maketext's maketext method, adding charset conversion and checking

Return value: translated string, or the argument itself if no translation is
found for thet argument.



---++ ObjectMethod *language* <tt>() -> $language_tag</tt>

Indicates the language tag of the current user's language, as detected from the
information sent by the browser. Returns the empty string if the language
could not be determined.



---++ ObjectMethod *enabled_languages* <tt>() -> %languages</tt>

Returns an array with language tags as keys and language (native) names as
values, for all the languages enabled in this TWiki.TWikiSite. Useful for
listing available languages to the user.



---++ ObjectMethod *fromSiteCharSet* <tt>($text) -> $encoded</tt>

This method receives =$text=, assumed to be encoded in {Site}{CharSet}, and
converts it to a internal representation.

Currently this representation will be a UTF-8 string, but this may change in
the future. This way, you can't assume any property on the returned value, and
should only use the returned value of this function as input to toSiteCharSet.
If you change the returnd value, either by removing, updating or appending
characters, be sure to touch only ASCII characters (i.e., characters that have
ord() less than 128).




---++ ObjectMethod *toSiteCharSet* <tt>($encoded) -> $text</tt>

This method receives a string, assumed to be encoded in TWiki's internal string
representation (as generated by the fromSiteCharSet method, and converts it
into {Site}{CharSet}.

When converting into {Site}{CharSet}, characters that are not present at that
charset are represented as HTML numerical character entities (NCR's), in the
format <code>&amp;#NNNN;</code>, where NNNN is the character's Unicode
codepoint.

See also: the =fromSiteCharSet= method.


@