/ 
Translate-Fluent-v0.6.1
River stage zero No dependents
/ Translate::Fluent::ResourceGroup

NAME

Translate::Fluent::ResourceGroup - a group of contextualized ResourceSets.

SYNOPSIS

my $group = Translate::Fluent::ResourceGroup->slurp_directory( "somedir" );
my $variables = {};

print $group->translate("some-resource", $variables, { language => "en" });

DESCRIPTION

Where Translate::Fluent::ResourceSet allow you to get translations from a single set of resources, Translate::Fluent::ResourceGroup provides the mechanisms to use multiple resource sets with basic rules to find the needed resource across multiple resource set.

This main idea behind this is that often we don't have perfect translations for our software, and that it is better to provide the text in the wrong language than not being able to provide a translation at all.

FALLBACK_ORDER

while creating a resource group you can define a list of context parameters to fall back through when looking for a resource (message or term). The order in which they are listed is the order in which they are released.

When one context paramater is released, the next possible value for that parameter is tested. For this purpose, language is special. The remaining parameters, when released, the value 'default' is used.

For language, the fallback path is a bit longer. If the language used in the translate context is a variant of a main language, then the main language is used. After the main language, then the default_language of the ResourceGroup is used (default is 'en'), and then 'dev' is used.

When a resource set is added to a group, all the context paramaters that are not defined when adding the resource set default to 'default' or 'dev' (dev for the language parameter).

Consider the following fallback order:

[qw( site plugin language )]

And now consider the following translate context:

{ site      => "google.com",
  plugin    => "footer",
  language  => "pt-br",
}

For this request, a given resource is going to be search is the ResourceSets that have the following contexts:

google.com > footer > pt-br
default    > footer > pt-br
google.com > default> pt-br
default    > default> pt-br
google.com > footer > pt
default    > footer > pt
google.com > default> pt
default    > default> pt
google.com > footer > en
default    > footer > en
google.com > default> en
default    > default> en
google.com > footer > dev
default    > footer > dev
google.com > default> dev
default    > default> dev

METHODS

new([...])

Creates a new ResourceGroup. possible parameters are:

  • fallback_order => [qw<...>]

    the fallback order defines the order with which context parameters of a translation request are relaxed to find a translation resource.

    context parameters that are not listed in the fallback_order are - at the moment - ignored, as having an arbitrary list of context parameters may make it very difficult to find any translation resources at all.

    This behavior may change in the future, so try to avoid using context parameters anywhere that are not listed in the fallback_order of the ResourceGroup.

    See #FALLBACK_ORDER above for details on the fallback mechanism.

  • default_language => '...'

    The default language is the language used when a translation request is made without a language context, or when the resource is not found in the given language.

    If a resource is still not found in the default_language, the default is to look for it using 'dev' for the language.

slurp_directory( $directory, $context )

slurp_directory load all the files fluent in a directory (and, optionally, sub-directories) and add all the resources found to the current ResourceGroup.

For convinience, if called as a static method, it created a new ResourceGroup and returns it.

When called as a static method, slurp_directory supports a few extra parameters in the $context, which are passed to new:

  • fallback_order

  • default_language

Additionally, $context can also include a value for recursive, which will define if files existing in sub-directories are also loaded or not.

All the remaining values in $context are used as values for the contexts of all the resources loaded.

context from files

Additionally, slurp_directory checks the first line of each file loaded to see if it matches:

#context: \w+[:=]\w+([,;]\w+[:=]\w+)*

(meaning, "$key: $value" pais separated by , or ;)

If the first line of the files match that, those values are added to the $context passed to slurp_directory.

To notice, values passed to slurp_directory have priority over those defined in the translation files.

add_resource_set( $resource_set, $context )

add_resource_set adds a pre-existing ResourceSet to a ResourceGroup with the context provided.

translate( $res_id, $variables, $context )

Search for a Message with the id $res_id using the $context provided and translates it.

get_term( $term_id, $context )

Search for a Term with the id $term_id using the $context provided and returns it. While this may be useful, it is intended for internal use.

get_message( $message_id, $context )

Search for a Message with the id $message_id using the $context provided and returns it. While this may be useful, it is intended for internal use.

While you could use the returned $message to perform a translation, this would fail when such translation needs a term or a message - which may not always happen. Do not do that.

SEE MORE

This file is part of Translate::Fluent - version, license and more general information can be found in its documentation.