class i18nTextCollector (View source)

SilverStripe-variant of the "gettext" tool: Parses the string content of all PHP-files and SilverStripe templates for occurrences of the _t() translation method. Also uses the i18nEntityProvider interface to get dynamically defined entities by executing the provideI18nEntities() method on all implementors of this interface.

Collects all found entities (and their natural language text for the default locale) into language-files for each module in an array notation. Creates or overwrites these files, e.g. framework/lang/en.yml.

The collector needs to be run whenever you make new translatable entities available. Please don't alter the arrays in language tables manually.

Usage through URL: http://localhost/dev/tasks/i18nTextCollectorTask Usage through URL (module-specific): http://localhost/dev/tasks/i18nTextCollectorTask/?module=mymodule Usage on CLI: sake dev/tasks/i18nTextCollectorTask Usage on CLI (module-specific): sake dev/tasks/i18nTextCollectorTask module=mymodule

Traits

A class that can be instantiated or replaced via DI

Constants

private THEME_PREFIX

Properties

protected string $defaultLocale

Default (master) locale

protected bool $warnOnEmptyDefault

Trigger if warnings should be shown if default is omitted

public string $basePath

The directory base on which the collector should act.

public string $baseSavePath

Save path

protected Writer $writer
protected Reader $reader

Translation reader

protected array $fileExtensions

List of file extensions to parse

protected array $classModuleCache

Map of translation keys => module names

Methods

public static 
create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

public static 
singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

public
__construct($locale = null)

No description

public
$this
setWriter(Writer $writer)

Assign a writer

public
getWriter()

Gets the currently assigned writer, or the default if none is specified.

public
getReader()

Get reader

public
$this
setReader(Reader $reader)

Set reader

public
run(array $restrictToModules = null, bool $mergeWithExisting = false)

This is the main method to build the master string tables with the original strings. It will search for existent modules that use the i18n feature, parse the _t() calls and write the resultant files in the lang folder of each module.

public
array
collect(array $restrictToModules = [], bool $mergeWithExisting = false)

Extract all strings from modules and return these grouped by module name

protected
array
resolveDuplicateConflicts(array $entitiesByModule)

Resolve conflicts between duplicate keys across modules

protected
array
getConflicts(array $entitiesByModule)

Find all keys in the entity list that are duplicated across modules

protected
string
getBestModuleForKey(array $entitiesByModule, string $key)

Determine the best module to be given ownership over this key

protected
string
findModuleForClass(string $class)

Given a partial class name, attempt to determine the best module to assign strings to.

protected
array
mergeWithExisting(array $entitiesByModule)

Merge all entities with existing strings

protected
array
getEntitiesByModule()

Collect all entities grouped by module

public
$this
write(Module $module, array $entities)

Write entities to a module

protected
array
processModule(Module $module)

Builds a master string table from php and .ss template files for the module passed as the $module param

protected
array
getFileListForModule(Module $module)

Retrieves the list of files for this module

public
array
collectFromCode(string $content, string $fileName, Module $module)

Extracts translatables from .php files.

public
array
collectFromTemplate(string $content, string $fileName, Module $module, array $parsedFiles = [])

Extracts translatables from .ss templates (Self referencing)

public
array
collectFromEntityProviders(string $filePath, Module $module = null)

Allows classes which implement i18nEntityProvider to provide additional translation strings.

public
array
collectFromORM(string $filePath)

Extracts translations for ORM fields

protected
string|bool
normalizeEntity(string $fullName, string $_namespace = null)

Normalizes entities with namespaces.

protected
array
getFilesRecursive(string $folder, array $fileList = [], string $type = null, string $folderExclude = '/\\/(tests)$/')

Helper function that searches for potential files (templates and code) to be parsed

public
getDefaultLocale()

No description

public
setDefaultLocale($locale)

No description

public
bool
getWarnOnEmptyDefault()

No description

public
$this
setWarnOnEmptyDefault(bool $warnOnEmptyDefault)

No description

Details

static Injectable create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

This method will defer class substitution to the Injector API, which can be customised via the Config API to declare substitution classes.

This can be called in one of two ways - either calling via the class directly, or calling on Object and passing the class name as the first parameter. The following are equivalent: $list = DataList::create(SiteTree::class); $list = SiteTree::get();

Parameters

mixed ...$args

Return Value

Injectable

static Injectable singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

It will always return the same instance for this class, which can be used for performance reasons and as a simple way to access instance methods which don't rely on instance data (e.g. the custom SilverStripe static handling).

Parameters

string $class

Optional classname to create, if the called class should not be used

Return Value

Injectable

The singleton instance

__construct($locale = null)

No description

Parameters

$locale

$this setWriter(Writer $writer)

Assign a writer

Parameters

Writer $writer

Return Value

$this

Writer getWriter()

Gets the currently assigned writer, or the default if none is specified.

Return Value

Writer

Reader getReader()

Get reader

Return Value

Reader

$this setReader(Reader $reader)

Set reader

Parameters

Reader $reader

Return Value

$this

run(array $restrictToModules = null, bool $mergeWithExisting = false)

This is the main method to build the master string tables with the original strings. It will search for existent modules that use the i18n feature, parse the _t() calls and write the resultant files in the lang folder of each module.

Parameters

array $restrictToModules
bool $mergeWithExisting

Merge new master strings with existing ones already defined in language files, rather than replacing them. This can be useful for long-term maintenance of translations across releases, because it allows "translation backports" to older releases without removing strings these older releases still rely on.

array collect(array $restrictToModules = [], bool $mergeWithExisting = false)

Extract all strings from modules and return these grouped by module name

Parameters

array $restrictToModules
bool $mergeWithExisting

Return Value

array

protected array resolveDuplicateConflicts(array $entitiesByModule)

Resolve conflicts between duplicate keys across modules

Parameters

array $entitiesByModule

List of all modules with keys

Return Value

array

Filtered listo of modules with duplicate keys unassigned

protected array getConflicts(array $entitiesByModule)

Find all keys in the entity list that are duplicated across modules

Parameters

array $entitiesByModule

Return Value

array

List of keys

protected string getBestModuleForKey(array $entitiesByModule, string $key)

Determine the best module to be given ownership over this key

Parameters

array $entitiesByModule
string $key

Return Value

string

Best module, if found

protected string findModuleForClass(string $class)

Given a partial class name, attempt to determine the best module to assign strings to.

Parameters

string $class

Either a FQN class name, or a non-qualified class name.

Return Value

string

Name of module

protected array mergeWithExisting(array $entitiesByModule)

Merge all entities with existing strings

Parameters

array $entitiesByModule

Return Value

array

protected array getEntitiesByModule()

Collect all entities grouped by module

Return Value

array

$this write(Module $module, array $entities)

Write entities to a module

Parameters

Module $module
array $entities

Return Value

$this

protected array processModule(Module $module)

Builds a master string table from php and .ss template files for the module passed as the $module param

Parameters

Module $module

Module instance

Return Value

array

An array of entities found in the files that comprise the module

See also

collectFromCode() and collectFromTemplate()

protected array getFileListForModule(Module $module)

Retrieves the list of files for this module

Parameters

Module $module

Module instance

Return Value

array

List of files to parse

array collectFromCode(string $content, string $fileName, Module $module)

Extracts translatables from .php files.

Note: Translations without default values are omitted.

Parameters

string $content

The text content of a parsed template-file

string $fileName

Filename Optional filename

Module $module

Module being collected

Return Value

array

Map of localised keys to default values provided for this code

array collectFromTemplate(string $content, string $fileName, Module $module, array $parsedFiles = [])

Extracts translatables from .ss templates (Self referencing)

Parameters

string $content

The text content of a parsed template-file

string $fileName

The name of a template file when method is used in self-referencing mode

Module $module

Module being collected

array $parsedFiles

Return Value

array

$entities An array of entities representing the extracted template function calls

array collectFromEntityProviders(string $filePath, Module $module = null)

Allows classes which implement i18nEntityProvider to provide additional translation strings.

Not all classes can be instantiated without mandatory arguments, so entity collection doesn't work for all SilverStripe classes currently

Parameters

string $filePath
Module $module

Return Value

array

array collectFromORM(string $filePath)

Extracts translations for ORM fields

Parameters

string $filePath

Return Value

array

protected string|bool normalizeEntity(string $fullName, string $_namespace = null)

Normalizes entities with namespaces.

Parameters

string $fullName
string $_namespace

Return Value

string|bool FALSE

protected array getFilesRecursive(string $folder, array $fileList = [], string $type = null, string $folderExclude = '/\\/(tests)$/')

Helper function that searches for potential files (templates and code) to be parsed

Parameters

string $folder

base directory to scan (will scan recursively)

array $fileList

Array to which potential files will be appended

string $type

Optional, "php" or "ss" only

string $folderExclude

Regular expression matching folder names to exclude

Return Value

array

$fileList An array of files

getDefaultLocale()

No description

setDefaultLocale($locale)

No description

Parameters

$locale

bool getWarnOnEmptyDefault()

No description

Return Value

bool

$this setWarnOnEmptyDefault(bool $warnOnEmptyDefault)

No description

Parameters

bool $warnOnEmptyDefault

Return Value

$this