| Wiki Markup |
|---|
| Warning |
Updated i18n functionality has been pushed to the FarCry 5.1 release. Once the initial 5.0 release is stabilised and the volatility of label changes has come down, we'll activate and test all the great i18n code that has been created to date. {warning} h2. Overview {excerpt} The webtop and COAPI (meaning all forms that use formtools) have been updated so that every label and description is translated. {excerpt} A resource bundle is a file that provides translations for in a particular language and region. As well as key-translation pairs, they typically also contain meta-information about a key-translation such as comments, creator, and modifier. In FarCry resource bundles are stored in /packages/resources/ in core, a plugin, or your project. Their filenames are in the form admin.properties (the default resource bundle) or |
Overview
| Excerpt |
|---|
The webtop and COAPI (meaning all forms that use formtools) have been updated so that every label and description is translated. |
A resource bundle is a file that provides translations for in a particular language and region. As well as key-translation pairs, they typically also contain meta-information about a key-translation such as comments, creator, and modifier.
In FarCry resource bundles are stored in /packages/resources/ in core, a plugin, or your project. Their filenames are in the form admin.properties (the default resource bundle) or admin_xx_yy.properties
...
(where
...
"xx"
...
and
...
"YY"
...
is
...
the
...
locale,
...
the
...
language
...
and
...
region
...
codes,
...
of
...
the
...
translation).
...
When
...
a
...
resource
...
is
...
requested
...
-
...
for
...
example
...
the
...
label
...
on
...
a
...
"Cancel"
...
button
...
-
...
the
...
system
...
first
...
looks
...
in
...
the
...
bundle
...
for
...
the
...
user's
...
locale,
...
then
...
in
...
the
...
default
...
or
...
base
...
bundle.
...
Translators
Translating is very straight forward. Open the base resource bundle (admin.properties)
...
for
...
the
...
core/plugin/project
...
in
...
a
...
resource
...
bundle
...
editor
...
like
...
...
...
or
...
the
...
...
...
...
.
...
Use
...
the
...
tool
...
to
...
create
...
a
...
bundle
...
for
...
the
...
locale
...
you
...
require
...
e.g.
...
en_AU
...
(Australian
...
english),
...
and
...
start
...
translating
...
the
...
key-translation
...
pairs.
...
| Info |
|---|
Regarding keys: At the moment no comments are stored for resources to say where they are used or how. Instead that information is encoded in the resource key. For example webtop labels and descriptions are stored inside a structure corresponding to the webtop structure - webtop.admin@label, content type forms are stored in a structure like coapi.typename.properties.property@label. Other keys reflect the area of the webtop (e.g. fixtree) or part of FarCry framework (e.g. workflow) they are used for, the use (e.g. workflow.buttons), the specific page element (e.g. workflow.buttons.save), then the element attribute (e.g. workflow.buttons.save@label). {info} |
To
...
test
...
the
...
translation
...
you
...
need
...
to
...
make
...
sure
...
that
...
the
...
locale
...
you
...
have
...
set
...
up
...
will
...
be
...
loaded
...
in
...
your
...
test
...
project.
...
The
...
project
...
locales
...
are
...
set
...
in
...
the
...
farcryConstructor
...
file
...
in
...
your
...
project
...
www
...
directory.
...
Once
...
this
...
setting
...
is
...
up
...
to
...
date
...
and
...
you
...
have
...
saved
...
your
...
new
...
bundle
...
in
...
the
...
relevant
...
/resources
...
directory,
...
restart
...
the
...
application.
...
Log
...
into
...
the
...
webtop,
...
edit
...
your
...
profile,
...
select
...
the
...
new
...
locale
...
from
...
the
...
list,
...
and
...
save.
...
When
...
you
...
reload
...
the
...
webtop
...
you
...
should
...
find
...
that
...
is
...
using
...
your
...
translations.
...
| Warning |
|---|
Some webtop elements are available as translated content but aren't included in the base bundle, and others are completely hard coded. An online tracking solution for these elements is in the works, but for the moment they should just be documented in a [|http://bugs.farcrycms.org/].{warning} h2. Developers Resource bundles are accessed by FarCry automatically through the webtop and the content type translations, and manually through the application.rb component. h3. Webtop Previously the webtop was translated by setting the label attribute in the xml to a variable (refering to the resource bundle struct in memory). With the refactoring, the label attribute is used to specify the DEFAULT VALUE. If the menu item has no corresponding resource, the default will be used. If it does it will be translated. This process also applies to the [Inline Webtop Documentation] feature. By default the menu item is mapped to a resource key in the format webtop.sectionid.subsectionid etc. The attribute is then added to this base key to differentiate it from other translated attributes. e.g. webtop.sectionid.subsectionid@label. The base key used for a menu item can be overridden by setting the rbkey attribute. This means that if you have an equivelent item in two places on your webtop you can override one to refer to the other. NOTE: this is not recommended - context is a significant factor when translating. h3. COAPI Translations of type, rule, and form text can currently be accessed through various i18n methods. In most cases these won't be necessary as all formtool tags are now automatically translated. h3. Manual access h4.. |
Developers
Resource bundles are accessed by FarCry automatically through the webtop and the content type translations, and manually through the application.rb component.
Webtop
Previously the webtop was translated by setting the label attribute in the xml to a variable (refering to the resource bundle struct in memory). With the refactoring, the label attribute is used to specify the DEFAULT VALUE. If the menu item has no corresponding resource, the default will be used. If it does it will be translated. This process also applies to the Inline Webtop Documentation feature.
By default the menu item is mapped to a resource key in the format webtop.sectionid.subsectionid etc. The attribute is then added to this base key to differentiate it from other translated attributes. e.g. webtop.sectionid.subsectionid@label.
The base key used for a menu item can be overridden by setting the rbkey attribute. This means that if you have an equivelent item in two places on your webtop you can override one to refer to the other. NOTE: this is not recommended - context is a significant factor when translating.
COAPI
Translations of type, rule, and form text can currently be accessed through various i18n methods. In most cases these won't be necessary as all formtool tags are now automatically translated.
Manual access
application.rb.getResource(key,
...
default,
...
locale)
...
Argument | Description | Default Value |
|---|---|---|
key | The key being requested | For consistency should be in the form category.subcategory.item@attribute, |
...
e.g. |
...
myplugin.thatform.thisdescription@text |
...
default | The default value (used if the key isn't |
...
found) |
...
The |
...
key |
...
string |
application.rb.formatRBString(rbString,
...
substituteValues,
...
default)
...
Argument | Description | Default Value |
|---|---|---|
rbString | The key being requested. Not changed to key for backwards compatability | See getResource |
substituteValues | Either a simple value to replace one value or an array to replace several. Variables defined in the resource string as {1} ... {n} | Required |
default | The default value (used if the key isn't found) | The key string |
Creating the base bundle
Developers who want to support community efforts to translate their plugins should include a complete base resource bundle in their project. To recap: this is a file called /packages/resources/admin.properties
...
in
...
your
...
plugin.
...
This
...
isn't
...
necessary
...
if
...
the
...
code
...
is
...
not
...
going
...
to
...
be
...
released
...
or
...
if
...
you're
...
happy
...
for
...
other
...
developers
...
to
...
complete
...
this
...
next
...
step.
...
By
...
default
...
FarCry
...
handles
...
the
...
lack
...
of
...
a
...
resource
...
bundle
...
invisibly
...
by
...
returning
...
the
...
default
...
values
...
provided
...
in
...
code.
...
The Resource Bundle Plugin provides functionality for automatically generating bundles based on default values, base bundles, or even with the Google Translate API. But it is important to remember that the automatic generation of the base bundle only handles resources that have been "touched". This means that a button label (for example) will only be known to the plugin if you have actually accessed the form.
Examples
Custom Admin
To i18n the webtop custom admin XML file you can define items as in the following example.
| Code Block |
|---|
<?xml version="1.0" encoding="utf-8"?>
<webtop>
<section mergeType="merge" id="content">
<subsection mergeType="merge" id="farGallery" label="[Image Gallery]">
<menu mergeType="merge" id="farSubSection" label="[Image Gallery]" labelType="value">
<menuitem mergeType="merge" id="farimagegallerylist" label="[Image Galleries]"
link="/admin/customadmin.cfm?module=customlists/farimagegallery.cfm&plugin=farcryimagegallery"
/>
</menu>
</subsection>
</section>
</webtop>
{code}
|
For
...
clarity,
...
I
...
tend
...
to
...
use
...
the
...
brackets
...
around
...
items
...
that
...
should
...
be
...
translated.
...
It
...
helps
...
to
...
locate
...
items
...
that
...
haven't
...
been
...
done
...
yet.
...
The
...
admin.properties
...
file
...
to
...
translate
...
the
...
above
...
entry
...
is
...
as
...
follows:
...
| Code Block |
|---|
webtop.content.farGallery@label=Image\ Gallery
webtop.content.farGallery.farSubSection@label=Image\ Gallery
webtop.content.farGallery.farSubSection.farimagegallerylist@label=Image\ Galleries
{code}
|
The
...
first
...
item,
...
webtop
...
,
...
is
...
used
...
to
...
denote
...
that
...
this
...
is
...
for
...
the
...
webtop
...
section
...
of
...
the
...
site.
...
The
...
rest
...
of
...
the
...
key
...
is
...
somewhat
...
like
...
an
...
xpath
...
statement
...
to
...
the
...
thing
...
you
...
want
...
to
...
translate.
...
They
...
are
...
the
...
IDs
...
of
...
each
...
node
...
in
...
the
...
XML,
...
and
...
then
...
the
...
final
...
statement
...
is
...
the
...
name
...
of
...
the
...
attribute
...
preceded
...
with
...
an
...
@
...
sign.
...
Content
...
Types
...
To
...
translate
...
the
...
labels
...
for
...
your
...
content
...
types
...
is
...
similar
...
to
...
how
...
you
...
do
...
the
...
webtop
...
translations
...
except
...
the
...
key's
...
path
...
is
...
slightly
...
different.
...
Using
...
the
...
example
...
of
...
this
...
content
...
type:
...
| Code Block |
|---|
<cfcomponent name="Image Gallery" displayname="Image Gallery"
extends="farcry.core.packages.types.types"
hint="A collection of images"
bObjectBroker="true"
ObjectBrokerMaxObjects="10000">
<cfproperty name="title" type="string" hint=""
ftseq="10" ftFieldset="General"
ftLabel="[Title]"
ftHint="Enter the title of your gallery."
ftvalidation="required" />
...
{code}
|
To
...
change
...
the
...
label
...
displayed
...
on
...
the
...
add
...
/
...
edit
...
form,
...
the
...
i18n
...
the
...
path
...
would
...
look
...
like
...
this:
...
| Code Block |
|---|
coapi.farImageGallery.properties.title@\[title\]=Title
{code}
The _coapi_ part is used to signify that it is a content type, and the _farImageGallery_ is the name of the content type (the name of the file, |
The coapi part is used to signify that it is a content type, and the farImageGallery is the name of the content type (the name of the file, farImageGallery.cfc).
...
The
...
next
...
part
...
properites
...
is
...
a
...
constant
...
to
...
allow
...
access
...
to
...
the
...
content
...
types
...
properties
...
and
...
must
...
be
...
typed
...
exactly
...
as
...
is:
...
properties
...
.
...
The
...
title
...
in
...
the
...
example
...
is
...
the
...
property
...
name
...
(as
...
defined
...
by
...
the
...
name
...
attribute
...
on
...
the
...
cfproperty).
...
The
...
final
...
part
...
of
...
the
...
path
...
statement
...
is
...
the
...
value
...
of
...
the
...
ftLabel
...
preceded
...
with
...
an
...
@
...
symbol.
...
It
...
is
...
important
...
to
...
note
...
that
...
this
...
is
...
the
...
value
...
of
...
the
...
ftLabel
...
not
...
the
...
term
...
ftLabel
...
.
...
It
...
is
...
also
...
important
...
to
...
note
...
that
...
the
...
[
...
and
...
]
...
characters
...
are
...
escaped.
...
If
...
you
...
do
...
not
...
use
...
those
...
charaters
...
in
...
the
...
ftLabel
...
value,
...
then
...
it
...
is
...
simply
...
the
...
value
...
by
...
it
...
self
...
(...
...
title@Title=...
...
for
...
example).
...
Refreshing
...
Locale
...
changes
...
If
...
you
...
make
...
changes
...
to
...
any
...
of
...
the
...
locale
...
files,
...
you
...
will
...
need
...
to
...
reload
...
the
...
application
...
to
...
see
...
the
...
changes.
...
The
...
easiest
...
way
...
to
...
to
...
a
...
reload
...
is
...
to
...
log
...
into
...
the
...
webtop,
...
and
...
click
...
on
...
the
...
Admin
...
tab.
...
From
...
there
...
select
...
the
...
Developer
...
Utilities
...
from
...
the
...
drop
...
down
...
on
...
the
...
left.
...
You
...
should
...
be
...
looking
...
at
...
Reinitialise
...
screen.
...
From
...
that
...
screen
...
you
...
can
...
tick
...
the
...
webtop
...
and
...
resource
...
bundles
...
check
...
boxes,
...
and
...
then
...
click
...
Update
...
Application
...
. See screen grab below.
