HelPHP

Language
in package

Tags
class

Language

The language class is a really important componant as it permit to make multi-language UI easily and to create real different user context. When you have to manage users, you have to think about how to adapt your display to usual aspects of life for the user : Does he read from left to right ? top to bottom ? Does a white background have the same meaning in all culture ? How to develop one app for everyone and adapt its display not only to the screen size (responsive design) but also to its culture.

First how to get some clue about user attemps ? Geolocalisation is not important, the user can be a traveler or using a proxy. The only clue is the language ! The navigator is in general set in the language of the user or in english for common professional purpose (like computing / dev ;) ). So first HelPHP detect the navigator language and if it's available in the app will autoswitch to it. If not, it will go the default language.

As you'll be able to edit your content depending the language, you'll be able to adapt your display.

Some tools are available working around this class :

  • the language module to manage them, and in its public part the showflags method that will display flags to enforce a language. Note that in any resquest if you add language=iso (iso code like en fr de ...) it will switch to the corresponding language.
  • the translate block in HelPHP_module create automaticaly input forms that are editable in multi language and saved in the DB.
  • the save_ and load_translation in HelPḦP_module will automate their saving loading
  • the get_tl method etc... you'll find in this class will help manage every aspect
  • the uitranslate module will help you translate your module UI and will create all the translations files (tl_xxx) next to your module files.
  • a connection to libretranslate in uitranslate and the translateblock will automate the translation in 36 languages : "fr","en", "de", "es", "ar", "fi", "ga", "hi", "hu", "id", "it", "ja", "ko", "pt", "pt", "sv", "uk", "bg", "bn", "ca", "cs", "da", "el", "az", "eo", "et", "fa", "he"
  • in your instance, in the tests folder, you find a translate.php test page
  • The indexation module will help you to create multilingual sitemap index, and it's automated from the document editor

Init.php will call create_instance method that will init the $LANG global to offer access to all method and states of this instancied class.

Table of Contents

Constants

id_attribute  = 'id_lang_data'
lang_module_name  = 'languages'
language_identifier  = 'language'
language_identifier used to identify request to switch the current language
long_translation_prefix  = 'lng_trnsl'
session_language_identifier  = 'language'
short_translation_prefix  = 'shrt_trnsl'
tl_long  = 'long'
tl_short translation field type constants for long inputs
tl_short  = 'short'
tl_short translation field type constants for short inputs
translation_prefix  = [\helPHP\libs\Language::tl_short => \helPHP\libs\Language::short_translation_prefix, \helPHP\libs\Language::tl_long => \helPHP\libs\Language::long_translation_prefix]

Properties

$context  : string
USeful var to make run a piece of in a different context so in another language practical case : when you preview a public page in its default language in the backoffice set with your language so it's used by default to make the difference between front and back UI.
$current_id_data  : mixed
$current_language  : mixed

Methods

__construct()  : mixed
clean_new_data()  : void
in the case where we post an element with the id = 0 (=> creation of a new element) we remove its information from the array and place it at the index of the new id created
create_instance()  : global
Call the construct to create the global instance $LANG
create_translation_name()  : mixed
create a translation input name to display in a form
delete_long_translation_value()  : bool
delete a long translation for one id
delete_short_translation_value()  : bool
delete a short translation for one id
delete_translation_data()  : bool
delete translation for one or more data id
extract_translation()  : string
retrieves the posted translation data corresponding to the specified field
get_available_language()  : string
doing nearly same job as validate_language() but will return an iso, the default one if the iso tested do not exist.
get_languages_data()  : array<string|int, mixed>
retrieves basic information of the authorized languages
get_multiple_tl()  : array<string|int, mixed>
returns an array with all identified texts, or the identifier in brackets if no text exists for this identifier
get_name()  : string
return the name stored in short table or the internal name if no entry in short.
get_tl()  : value
return the identified text, or the identifier between braces if no text exists for this identifier
get_translated_table_fields()  : array<string|int, mixed>
return translated wordings for array of field names
get_translated_text_from_other_module()  : value
return the identified text, or the identifier between braces if no text exists for this identifier but from another tl file than the one corresponding to the current module.
load_long_translation_collection()  : array<string|int, mixed>
load a list of long translation id and value for a possible use with quick edit
load_long_translation_value()  : string
load a long translation value
load_long_translation_value_list()  : array<string|int, mixed>
returns several long values according to a series of fields identifier
load_public_translation_data()  : void
filling $post with translation data from the database, working like load_translation_data but it's in general used for public side because it's loading only current language data for display.
load_short_translation_collection()  : array<string|int, mixed>
load a list of short translation id and value for a possible use with quick edit
load_short_translation_value()  : string
load a short translation value
load_short_translation_value_list()  : array<string|int, mixed>
returns several short values according to a series of fields identifier
load_translation_data()  : void
filling $post with translation data from the database it's in general used for admin side because it's loading all language data for editing.
load_translation_file_common()  : mixed
load the common translation file from libs/tl
load_translation_files()  : result
load translation data from a 'tl_' module file
prepare_posted_translation_data()  : array<string|int, mixed>
formatting of posted data for easier processing
save_long_translation_value()  : bool
Save a long translation value
save_short_translation_value()  : bool
Save a short translation value
save_translation_data()  : void
save posted translation data in the database IMPORTANT ! If a new element must be created (id = 0) and it has already been created previously, you must specify the name of the entry containing this new id in $post via the parameter $created_item_identifier or directly give the value of the id to this parameter
set_context()  : void
Create a different context to use another language in sz
set_language_iso()  : string
Switch the current language depending iso
translate()  : array<string|int, mixed>
It send calls to libretranslate (can be a local docker container).
update_session()  : void
Update_session if some vars of the instance should be copied in the session
validate_language()  : bool
checks that the language specified in parameter is authorized / available

Constants

id_attribute

public mixed id_attribute = 'id_lang_data'

lang_module_name

public mixed lang_module_name = 'languages'

language_identifier

language_identifier used to identify request to switch the current language

public string language_identifier = 'language'

long_translation_prefix

public mixed long_translation_prefix = 'lng_trnsl'

session_language_identifier

public mixed session_language_identifier = 'language'

short_translation_prefix

public mixed short_translation_prefix = 'shrt_trnsl'

tl_long

tl_short translation field type constants for long inputs

public string tl_long = 'long'

tl_short

tl_short translation field type constants for short inputs

public string tl_short = 'short'

translation_prefix

public mixed translation_prefix = [\helPHP\libs\Language::tl_short => \helPHP\libs\Language::short_translation_prefix, \helPHP\libs\Language::tl_long => \helPHP\libs\Language::long_translation_prefix]

Properties

$context

USeful var to make run a piece of in a different context so in another language practical case : when you preview a public page in its default language in the backoffice set with your language so it's used by default to make the difference between front and back UI.

public static string $context = ''

$current_id_data

public mixed $current_id_data = ''

$current_language

public mixed $current_language = ''

Methods

__construct()

public __construct([mixed $new_context = '' ]) : mixed
Parameters
$new_context : mixed = ''

clean_new_data()

in the case where we post an element with the id = 0 (=> creation of a new element) we remove its information from the array and place it at the index of the new id created

public static clean_new_data(array<string|int, mixed> &$post, int $new_id) : void
Parameters
$post : array<string|int, mixed>
$new_id : int

create_instance()

Call the construct to create the global instance $LANG

public static create_instance([mixed $context = '' ]) : global
Parameters
$context : mixed = ''
Return values
global —

$LANG

create_translation_name()

create a translation input name to display in a form

public static create_translation_name(string $name, int $id, int $lang_id, string $type) : mixed
Parameters
$name : string

identification name of the field, in the format "module_table-field"

$id : int

id of the entry in the table

$lang_id : int

id of the language, taken from the languages_data table

$type : string

type of field, to be taken from the different types defined as constants in the language class (short/long)

Tags
@return

[type]

delete_long_translation_value()

delete a long translation for one id

public static delete_long_translation_value(mixed $field_identifier, mixed $id[, int $id_lang_data = 0 ]) : bool
Parameters
$field_identifier : mixed

name of the posted input, in the format "module_table-field"

$id : mixed

in the db

$id_lang_data : int = 0
Return values
bool

delete_short_translation_value()

delete a short translation for one id

public static delete_short_translation_value(mixed $field_identifier, mixed $id[, int $id_lang_data = 0 ]) : bool
Parameters
$field_identifier : mixed

name of the posted input, in the format "module_table-field"

$id : mixed

in the db

$id_lang_data : int = 0
Return values
bool

delete_translation_data()

delete translation for one or more data id

public static delete_translation_data(array<string|int, mixed> &$post, string $module, string $table[, int|array<string|int, mixed>|string $filter = null ]) : bool
Parameters
$post : array<string|int, mixed>

the current post

$module : string

name of the module

$table : string

name of the table

$filter : int|array<string|int, mixed>|string = null

selection filter, can be an id, a array list of ids or a string containing a mysql subquery

Return values
bool

extract_translation()

retrieves the posted translation data corresponding to the specified field

public static extract_translation(array<string|int, mixed> &$post, string $field_identifier, int $id) : string
Parameters
$post : array<string|int, mixed>
$field_identifier : string

name of the posted input, in the format "module_table-field"

$id : int

id of the entry in the database

Return values
string —

value

get_available_language()

doing nearly same job as validate_language() but will return an iso, the default one if the iso tested do not exist.

public get_available_language([string $lang = '' ]) : string
Parameters
$lang : string = ''
Return values
string —

iso same as $lang if available or the default one .

get_languages_data()

retrieves basic information of the authorized languages

public get_languages_data() : array<string|int, mixed>
Return values
array<string|int, mixed> —

for each language we'll have: id_data = id in languages_data iso = language code on 2 letters (except in Chinese where it can go up to 7) label = name of the language in English own = name of the language, in its native

get_multiple_tl()

returns an array with all identified texts, or the identifier in brackets if no text exists for this identifier

public get_multiple_tl(mixed $module_name, array<string|int, mixed> $list[, null $join = null ]) : array<string|int, mixed>
Parameters
$module_name : mixed
$list : array<string|int, mixed>

that contains another array like this: ['key'=>'string identifier' , 'replace'=>[...] ] replace can contain a word or an array of words each word will replace in order the numbered markers preceded by $ present in the text=

$join : null = null

if $join is specified, the result will be a string concatenated with this text instead of an array

Return values
array<string|int, mixed> —

or string

get_name()

return the name stored in short table or the internal name if no entry in short.

public static get_name(string $module_table, int $id_item) : string

Used to get the name to display for elements like category that may have some multilingual entry.

Parameters
$module_table : string

the table of the field name. used to form the field_identifier like module_table-name

$id_item : int
Return values
string —

name

get_tl()

return the identified text, or the identifier between braces if no text exists for this identifier

public get_tl(mixed $module_name[, string $key = '' ][, string|array<string|int, mixed> $replace = null ][, int $count_for_singular = null ][, array<string|int, mixed> $array = false ]) : value
Parameters
$module_name : mixed
$key : string = ''

the key is the id in the tl file, for exemple the word "chicken" and in the tl file [chicken]=>"un poulet" if ($count_for_singular > 1) will search for the $key plural : [chickens] => "des poulets" $key.'__none' matches none (so $count_for_singular == 0) to force some expression : [chicken_none] => "pas de poulet" $key.'__singular' matches the singular (i. e. $count_for_singular == 1) : [chicken_singular] => "un poulet" so depending $count_for_singular and the key "chicken" we will search for a translation that will adapt to the number.

$replace : string|array<string|int, mixed> = null

can contain a word or an array of words : if there is a string it will replace $1 in the tl string if it's a key/pair array like this : 1=>"text",2=>"another one" , it will replace $1 by "text" and $2 by "another text" so each word will replace in order the numbered markers preceded by $ present in the text

$count_for_singular : int = null

is used if the phrase needs to be converted to the plural or not based on a quantity

$array : array<string|int, mixed> = false

to search in another array the module tl

Return values
value

get_translated_table_fields()

return translated wordings for array of field names

public get_translated_table_fields(string $module_name, string $table, array<string|int, mixed> $fields) : array<string|int, mixed>
Parameters
$module_name : string
$table : string
$fields : array<string|int, mixed>

list of names

Return values
array<string|int, mixed>

get_translated_text_from_other_module()

return the identified text, or the identifier between braces if no text exists for this identifier but from another tl file than the one corresponding to the current module.

public get_translated_text_from_other_module([string $other_module = '' ][, bool $admin = false ][, string $key = '' ][, string|array<string|int, mixed> $replace = null ][, int $count_for_singular = null ]) : value

by specifiyng $other_module name and it's admin or not it will load the othe module tl file before searching in it the wordings like get_tl

Parameters
$other_module : string = ''

name

$admin : bool = false

true false

$key : string = ''

the key is the id in the tl file, for exemple the word "chicken" and in the tl file [chicken]=>"un poulet" if ($count_for_singular > 1) will search for the $key plural : [chickens] => "des poulets" $key.'__none' matches none (so $count_for_singular == 0) to force some expression : [chicken_none] => "pas de poulet" $key.'__singular' matches the singular (i. e. $count_for_singular == 1) : [chicken_singular] => "un poulet" so depending $count_for_singular and the key "chicken" we will search for a translation that will adapt to the number.

$replace : string|array<string|int, mixed> = null

can contain a word or an array of words : if there is a string it will replace $1 in the tl string if it's a key/pair array like this : 1=>"text",2=>"another one" , it will replace $1 by "text" and $2 by "another text" so each word will replace in order the numbered markers preceded by $ present in the text

$count_for_singular : int = null

is used if the phrase needs to be converted to the plural or not based on a quantity

Return values
value

load_long_translation_collection()

load a list of long translation id and value for a possible use with quick edit

public static load_long_translation_collection(string $field_identifier[, int $id_lang_data = 0 ]) : array<string|int, mixed>
Parameters
$field_identifier : string

name of the posted input, in the format "module_table-field"

$id_lang_data : int = 0

of the lang coming from languages_data

Return values
array<string|int, mixed> —

list of result

load_long_translation_value()

load a long translation value

public static load_long_translation_value(string $field_identifier, int $id[, int $id_lang_data = 0 ]) : string
Parameters
$field_identifier : string

name of the posted input, in the format "module_table-field"

$id : int

in the db

$id_lang_data : int = 0

of the lang coming from languages_data

Return values
string —

$value

load_long_translation_value_list()

returns several long values according to a series of fields identifier

public static load_long_translation_value_list(array<string|int, mixed> $fields_identifier_list, int $id[, int $id_lang_data = 0 ]) : array<string|int, mixed>
Parameters
$fields_identifier_list : array<string|int, mixed>

list ofname of the posted input, in the format "module_table-field"

$id : int

in the db

$id_lang_data : int = 0

of the lang coming from languages_data

Return values
array<string|int, mixed> —

of string values

load_public_translation_data()

filling $post with translation data from the database, working like load_translation_data but it's in general used for public side because it's loading only current language data for display.

public static load_public_translation_data(array<string|int, mixed> &$post, string $module, string $table[, int|array<string|int, mixed>|string $filter = null ]) : void
Parameters
$post : array<string|int, mixed>

current $post

$module : string

module name

$table : string

table name

$filter : int|array<string|int, mixed>|string = null

selection filter, can be an id, a array list of ids or a string containing a mysql subquery

Return values
void —

it's filling $post

load_short_translation_collection()

load a list of short translation id and value for a possible use with quick edit

public static load_short_translation_collection(string $field_identifier[, int $id_lang_data = 0 ]) : array<string|int, mixed>
Parameters
$field_identifier : string

name of the posted input, in the format "module_table-field"

$id_lang_data : int = 0

of the lang coming from languages_data

Return values
array<string|int, mixed> —

list of result

load_short_translation_value()

load a short translation value

public static load_short_translation_value(string $field_identifier, int $id[, int $id_lang_data = 0 ]) : string
Parameters
$field_identifier : string

name of the posted input, in the format "module_table-field"

$id : int

in the db

$id_lang_data : int = 0

of the lang coming from languages_data

Return values
string —

$value

load_short_translation_value_list()

returns several short values according to a series of fields identifier

public static load_short_translation_value_list(array<string|int, mixed> $fields_identifier_list, int $id[, int $id_lang_data = 0 ]) : array<string|int, mixed>
Parameters
$fields_identifier_list : array<string|int, mixed>

list of name of the posted input, in the format "module_table-field"

$id : int

in the db

$id_lang_data : int = 0

of the lang coming from languages_data

Return values
array<string|int, mixed> —

of string values

load_translation_data()

filling $post with translation data from the database it's in general used for admin side because it's loading all language data for editing.

public static load_translation_data(array<string|int, mixed> &$post, string $module, string $table[, int|array<string|int, mixed>|string $filter = null ]) : void
Parameters
$post : array<string|int, mixed>

current $post

$module : string

module name

$table : string

table name

$filter : int|array<string|int, mixed>|string = null

selection filter, can be an id, a array list of ids or a string containing a mysql subquery

Return values
void —

it's filling $post

load_translation_file_common()

load the common translation file from libs/tl

public load_translation_file_common() : mixed
Tags
@return

void, filling the global $tl

load_translation_files()

load translation data from a 'tl_' module file

public load_translation_files(string $module_name[, bool $admin = false ][, bool $only_common = false ][, string $module_path = false ]) : result
Parameters
$module_name : string
$admin : bool = false

=false

$only_common : bool = false

=false

$module_path : string = false

=false if the module is not in a classic place.

Return values
result —

in $tl

prepare_posted_translation_data()

formatting of posted data for easier processing

public static prepare_posted_translation_data(mixed $post) : array<string|int, mixed>
Parameters
$post : mixed
Return values
array<string|int, mixed>

save_long_translation_value()

Save a long translation value

public static save_long_translation_value(string $field_identifier, int $id, string $value[, int $id_lang_data = 0 ]) : bool
Parameters
$field_identifier : string

name of the posted input, in the format "module_table-field"

$id : int

in the db

$value : string

content to save

$id_lang_data : int = 0

of the lang coming from languages_data

Return values
bool —

true if ok

save_short_translation_value()

Save a short translation value

public static save_short_translation_value(string $field_identifier, int $id, string $value[, int $id_lang_data = 0 ]) : bool
Parameters
$field_identifier : string

name of the posted input, in the format "module_table-field"

$id : int

in the db

$value : string

content to save

$id_lang_data : int = 0

of the lang coming from languages_data

Return values
bool —

true if ok

save_translation_data()

save posted translation data in the database IMPORTANT ! If a new element must be created (id = 0) and it has already been created previously, you must specify the name of the entry containing this new id in $post via the parameter $created_item_identifier or directly give the value of the id to this parameter

public static save_translation_data(array<string|int, mixed> &$post[, int $created_item_identifier = null ]) : void
Parameters
$post : array<string|int, mixed>
$created_item_identifier : int = null

set_context()

Create a different context to use another language in sz

public set_context([string $new_context = '' ]) : void
Parameters
$new_context : string = ''

set_language_iso()

Switch the current language depending iso

public set_language_iso(mixed $iso) : string
Parameters
$iso : mixed
Return values
string —

current language iso

translate()

It send calls to libretranslate (can be a local docker container).

public static translate(string $text, string $format, string $iso_original[, array<string|int, mixed> $iso_targets = [] ]) : array<string|int, mixed>

URL and api_key of libretranslate are set in the main config.

Parameters
$text : string

original to translate

$format : string

json

$iso_original : string
$iso_targets : array<string|int, mixed> = []

=[] of iso to translate to.

Return values
array<string|int, mixed> —

key pairs iso=>translation

update_session()

Update_session if some vars of the instance should be copied in the session

public update_session() : void

validate_language()

checks that the language specified in parameter is authorized / available

public validate_language(string $lang) : bool
Parameters
$lang : string
Return values
bool —

true false


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results