There are no dedicated showcase example pages for the Uize.Services.LocAdapter module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Services.LocAdapter module...

SEARCH

The Uize.Services.LocAdapter module defines the Uize.Services.LocAdapter class, which is a subclass of Uize.Service.Adapter.

INHERITANCE CHAIN

Uize.Class −> Uize.Service.Adapter −> Uize.Services.LocAdapter

1.2.1. Features Introduced in This Module

1.2.2. Features Overridden in This Module

1.2.3. Features Inherited From Other Modules

1.2.4. Modules Directly Under This Namespace

1.2.5. Unit Tests

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Distributes the resource strings from the specified project resource strings object to a project's codebase as resource files.

SYNTAX

this.distributeResources (stringResourcesOBJ,languageSTR);

The distributeResources method iterates through the project resource strings object passed to it and uses the serializeResourceFile instance method to generate the contents for resource files that are then written to the codebase of the project. A language identifier should be passed to the languageSTR parameter so that the distributeResources method can know for which language resource files are to be generated - this information will govern the naming of the generated files.

In addition to being used internally in the implementation of the import localization service method, the distributeResources method can be used in the implementation of the extract localization service method for generating resource files for the primary language, based upon resource strings that have been extracted from the project's source code files.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified brand supports the specified language.

SYNTAX

supportsLanguageBOOL = this.doesBrandSupportLanguage (brandIdSTR,languageSTR);

Whether or not a particular language is supported for a brand is governed by the brand language configuration for a project. Internally, the doesBrandSupportLanguage method is used in the implementation of the export localization service method to determine if branded resource strings should be gathered for any given translatable language for which strings are being exported.

If an empty string is specified for the brandIdSTR parameter, or if the language identifier for the pseudo-locale that is configured for the project is specified for the languageSTR parameter, then the doesBrandSupportLanguage method will return the value true.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Returns a project resource strings object, being the complete set of resource strings for the primary language of a project, as parsed from all the primary language resource files of the project.

SYNTAX

stringResourcesOBJ = this.gatherResources ();

The gatherResources method recurses through all the folders under the configured root folder path for a project, finding all the resource files (as determined by the isResourceFile instance method), and parses the resource strings from these files using the parseResourceFile instance method. The parsed resource strings are populated into the master project resource strings object.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Returns a string, representing the file path for a language specific version of the specified primary language resource file.

SYNTAX

resourcePathSTR = this.getLanguageResourcePath (primaryLanguageResourcePathSTR,languageSTR);

The primaryLanguageResourcePathSTR parameter is used to specify the path for the primary language version of a specific resource file, while the languageSTR parameter is used to specify the language for which a language specific resource file path should be generated.

The implementation of the getLanguageResourcePath method should take the values for these two parameters and then use the project specific rules for resource file naming and organization to derive the path for the language specific version of the resource file and return this path.

The getLanguageResourcePath method is used when generating resource files in the codebase for all the translatable languages configured for a project. This method must be overridden by subclasses, since the base class' version contains no implementation and will throw an exception if called.

IMPLEMENTATION INFO

Returns an array, containing the locale codes for all the languages configured for the project, including the primary language and the pseudo-locale.

SYNTAX

languagesARRAY = this.getLanguages ();

NOTES

IMPLEMENTATION INFO

Returns a string references lookup object, representing the information for zero or more resource string references detected within the specified code file.

SYNTAX

stringReferencesOBJ = this.getReferencesFromCodeFile (filePathSTR);

The usage method iterates over the list of referencing files that is returned by the getReferencingCodeFiles instance method and, for each file, uses the getReferencesFromCodeFile instance method to obtain the file's resource string references.

The implementation of this method, provided in this base class, throws an error. This means that, if the usage localization service method is to be used for a project, then this method must be overridden by the adapter subclass for the project.

When the getReferencesFromCodeFile method is called, the file path for a code file is passed to its filePathSTR parameter. As an instance method, an implementation for this method can access the project properties through the properties of the instance.

The implementation can detect resource string references in any way that suits the nature of the project and the language(s) of its code files. The only requirement is that the method return a lookup object of string references arrays, where the keys of the lookup object are string ID's, and where the values of the lookup are references arrays containing any number of reference info objects describing the references to the string within the code file.

STRING REFERENCES LOOKUP OBJECT

{
  myString1:[
    {
      // reference info
    },
    {
      // reference info
    },
    ...
  ],
  myString2:[
    {
      // reference info
    },
    {
      // reference info
    },
    ...
  ],
  ...
  ...
  ...
  myStringN:[
    {
      // reference info
    },
    {
      // reference info
    },
    ...
  ]
}

The information that is returned in the string reference objects is left to the discretion of the adapter subclass for the project. The following structure is recommended as a guideline...

STRING REFERENCE OBJECT

{
  reference:referenceTextSTR,
  start:{
    line:startLineINT,          // the line number where the reference starts
    lineChar:startLineCharINT,  // the starting character on the starting line
    char:startCharINT           // the starting character within the file
  },
  end:{
    line:endLineINT,            // the line number where the reference ends
    lineChar:endLineCharINT,    // the ending character on the ending line
    char:endCharINT             // the ending character within the file
  }
}

NOTES

IMPLEMENTATION INFO

Returns an array of file paths, representing the code files in a project's codebase that may contain references to resource strings.

SYNTAX

filePathsARRAY = this.getReferencingCodeFiles ();

The implementation of this method, provided in this base class, throws an error. This means that, if the usage localization service method is to be used for a project, then this method must be overridden by the adapter subclass for the project.

The getReferencingCodeFiles method is not passed any parameters when it is called. As an instance method, an implementation for this method can access the project properties through the properties of the instance. The implementation can determine the list of referencing files in any way that suits the nature of the project. The only requirement is that the method return an array of file paths.

The usage method iterates over the list of referencing files that is returned by this method and, for each file, uses the getReferencesFromCodeFile instance method to obtain the file's resource string references.

NOTES

IMPLEMENTATION INFO

Returns a string, representing the brand ID for the specified resource file, or an empty string if the resource file is brand-neutral.

SYNTAX

brandIdSTR = this.getResourceFileBrand (resourceFilePathSTR);

The implementation of this method, provided in this base class, simply returns an empty string. This method can be optionally overridden by subclasses, for projects that support branded resources.

NOTES

IMPLEMENTATION INFO

Returns a string, representing the brand ID for the specified resource string, or an empty string if the resource string is brand-neutral.

SYNTAX

brandIdSTR = this.getStringBrand (stringPathARRAY);

The implementation of this method, provided in this base class, simply returns an empty string. This method can be optionally overridden by subclasses, for projects that support branded resources.

When the getStringBrand method is called, a value is passed for the stringPathARRAY parameter that specifies the full path to the string, where the first element in the path array specifies the path for the resource file to which the string belongs, and the remaining elements of the path array specify the location of the string internal to the resource file (this may consist of simply a key element, or multiple elements if the resource files for a project are hierarchical rather than flat).

NOTES

IMPLEMENTATION INFO

Returns an array, containing the locale codes for all the translatable languages configured for the project (i.e. excluding the primary language and the pseudo-locale).

SYNTAX

translatableLanguagesARRAY = this.getTranslatableLanguages ();

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified file path is for a brand resource file.

SYNTAX

isBrandResourceFileBOOL = this.isBrandResourceFile (filePathSTR);

The implementation of this method, provided in this base class, leverages the related getResourceFileBrand instance method and returns true if the value returned by the getResourceFileBrand method is truthy. This method can be optionally overridden by subclasses to determine if a resource file is for a brand in a different manner.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified resource string is for a brand.

SYNTAX

isBrandResourceStringBOOL = this.isBrandResourceString (resourceStringPathARRAY);

The implementation of this method, provided in this base class, leverages the related getStringBrand instance method and returns true if the value returned by the getStringBrand method is truthy.

This method can be optionally overridden by subclasses, if it is necessary to determine if a resource string is for a brand in some different manner. When the isBrandResourceString method is called, it is passed a value for the resourceStringPathARRAY parameter that is a path array, where the last element can be regarded as the string key. An implementation for this method may use any elements of the path array to determine whether or not the string is for a brand.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified file is a resource file.

SYNTAX

isResourceFileBOOL = this.isResourceFile (filePathSTR);

The implementation of this method, provided in this base class, throws an error. This means that this method must be overridden by an adapter subclass for a project.

When the isResourceFile method is called, it is passed a value for the filePathSTR parameter that specifies the path for the file being tested, that is relative to the configured root folder path for the project.

An implementation for this method can perform any test against the file path to determine whether or not the file is a resource file. Assuming that a project follows a sensible naming convention for resource files, it is quite reasonable to use a regular epxression based match.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not a string's key is valid.

SYNTAX

isValidBOOL = this.isStringKeyValid (stringPathARRAY);

The implementation of this method, provided in this base class, always returns the value true.

When the isStringKeyValid method is called, a value is passed for the stringPathARRAY parameter that specifies the full path to the string. Generally, the key is considered to be the very last element in the string path array, but an implementation of this method can use any or all of the elements of the path array to determine if the string's "key" is valid.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not a string is considered to be long.

SYNTAX

isLongBOOL = this.isStringLong (stringMetricsOBJ);

The implementation of this method, provided in this base class, judges a string to be long if it contains more than 50 words or more than 500 characters.

When the isStringLong method is called, a string metrics object is passed as a value to the stringMetricsOBJ parameter. The string metrics object is generated by the Uize.Loc.Strings.Metrics.getStringMetrics method of the Uize.Loc.Strings.Metrics module and contains information on the word count and character count of the string. This information can be used in the implementation of the isStringLong method.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the name of a substitution token is considered weak.

SYNTAX

isWeakBOOL = this.isTokenWeak (tokenNameSTR);

The implementation of this method, provided in this base class, judges the name of a token to be weak if it is less than three characters in length, or if it is a number.

When the isTokenWeak method is called, the name of a token to test is passed to the tokenNameSTR parameter. An implementation of this method can use any criteria suitable to the project to determine whether or not a token name is weak.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified string is translatable.

SYNTAX

isTranslatableBOOL = this.isTranslatableString (stringInfoOBJ);

The implementation of this method, provided in this base class, always returns the value true. If the resource files for a project are expected to contain any strings that should never be translated, then this method should be overridden in an adapter subclass for the project to return the value false for such strings.

When the isTranslatableString method is called, a value is passed for the stringInfoOBJ parameter that provides information about the string and is of the form...

STRING INFO

{
  key:keySTR,     // the key of the string path
  value:valueSTR  // the text of the string
}

2.30.1. Techniques for Determining Translatability

2.30.2. How the Result is Used

2.30.3. Pure Whitespace is Not Translatable

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Informs the method progress logger of the completion of a localization service method's execution.

SYNTAX

this.methodExecutionComplete (summarySTR);

The methodExecutionComplete method is used internally in the implementations for localization service methods, such as the export method. When used, it should be called after all steps in the execution of a method have been completed. A string value should be passed for the summarySTR parameter, so that summary information can be logged for the method.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Returns a resource strings object, being the resource strings parsed from the specified resource file.

SYNTAX

resourceStringsOBJ = this.parseResourceFile (resourceFileTextSTR,resourceFileInfoOBJ);

The implementation of this method, provided in this base class, throws an error. This means that this method must be overridden by an adapter subclass for a project.

When the parseResourceFile method is called, two parameters are passed to it: resourceFileTextSTR and resourceFileInfoOBJ.

2.37.1. resourceFileTextSTR

2.37.2. resourceFileInfoOBJ

{
  path:filePathSTR,
  language:localeSTR,
  isPrimaryLanguage:isPrimaryLanguageBOOL
}

NOTES

IMPLEMENTATION INFO

Prepares the method progress logger to expect the specified number of total steps to be performed during execution of a method.

SYNTAX

this.prepareToExecuteMethod (totalStepsINT);

The prepareToExecuteMethod method is used internally in the implementations for localization service methods, such as the export method. When used, it should be called early in the execution of a localization method, after the scope of the method's work has been determined, but before any of the work has been performed. Thereafter, the related stepCompleted and methodExecutionComplete methods should be used.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Returns a string, being a pseudo-localized version of the specified resource string.

SYNTAX

pseudoLocalizedSTR = this.pseudoLocalizeString (stringInfoOBJ,pseudoLocalizationOptionsOBJ);

When the resource strings for a project are exported using the export localization service method, pseudo-localized values for all translatable strings are automatically generated for the configured pseudo-locale of the project. These pseudo-localized values are created by calling the pseudoLocalizeString method.

The implementation of this method, provided in this base class, pseudo-localizes resource strings by calling the Uize.Loc.Pseudo.pseudoLocalize method of the Uize.Loc.Pseudo module. This behavior is generally adequate for most projects. However, the implementation of this method can optionally be overridden in an adapter subclass for a project if any kind of special handling might be needed for specific strings, or if a different process of pseudo-localization needs to be employed.

When the pseudoLocalizeString method is called, two parameters are passed to it: stringInfoOBJ and stringValueSTR.

2.41.1. stringInfoOBJ

{
  key:keySTR,      // the key of the string path
  value:valueSTR,  // the text of the string
  path:pathSTR     // the full path of the resource string
}

2.41.2. pseudoLocalizationOptionsOBJ

IMPLEMENTATION INFO

Returns a string, being the specified resource strings object serialized to the text contents of a resource file.

SYNTAX

resourceFileTextSTR = this.serializeResourceFile (resourceStringsOBJ,resourceFileInfoOBJ);

The implementation of this method, provided in this base class, throws an error. This means that this method must be overridden by an adapter subclass for a project.

When the serializeResourceFile method is called, two parameters are passed to it: resourceStringsOBJ and resourceFileInfoOBJ.

2.42.1. resourceStringsOBJ

2.42.2. resourceFileInfoOBJ

{
  path:filePathSTR,
  language:localeSTR,
  isPrimaryLanguage:isPrimaryLanguageBOOL
}

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Informs the method progress logger of the completion of one of the steps of a localization service method's execution.

SYNTAX

this.stepCompleted (messageSTR);

The stepCompleted method is used internally in the implementations for localization service methods, such as the export method. When used, it should be called during the execution of a localization service method, exactly as many times as the number of total steps specified when earlier calling the prepareToExecuteMethod method. A string value should be passed for the messageSTR parameter, so that information about the step that has been completed can be logged.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified string contains HTML tags.

SYNTAX

hasHtmlBOOL = this.stringHasHtml (stringPathARRAY,stringValueSTR);

The implementation of this method, provided in this base class, performs a very simple (and performant), regular expression match based test to determine if a string contains HTML tags. Some projects may use a format for substitution tokens that resembles the HTML tag format, and this may confuse the test in the base class' implementation of this method. In such cases, this method can be overridden in a subclass.

When the stringHasHtml method is called, two parameters are passed to it: stringPathARRAY and stringValueSTR.

2.45.1. stringPathARRAY

2.45.2. stringValueSTR

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO