Python Client Introduction

Introduction

Several python files are provided as the python client to support accessing Singleton service, making Singleton users to handle its globalization easily.

Features in Python Client

• Getting configuration content.
• Getting the translation.
• Getting messages of a locale.

Prerequisites

Python 2.x

Python 3.x

It’s better to install PyYAML module of python. Otherwise, the configuration file should be written in json.

If formats like Plural, Date, Number are needed, please install PyICU after icu4c is installed on the operating system.

How to use python client as a python package

Install sgtnclient as a python package.

pip install sgtnclient

pip3 install sgtnclient

How to get and use the client code

git clone -b g11n-python-client https://github.com/vmware/singleton.git

Install it as a python package.

python setup.py install

Or use its code directly by putting them to a place where they can be imported to the application code.

How to write a configuration file

The python client of Singleton needs a configuration file. Here is an example.

• Basic definition

• Extended definition

• Component definition

• Special string for component definition

• Example of component definition in original way

components:
  - name: about
    locales:
      - language_tag: en-US
        offline_resources_path:
          - about/messages.properties
      - language_tag: de
        offline_resources_path:
          - about/messages_de.json
      - language_tag: fr
        offline_resources_path:
          - about/messages_fr.json
  - name: common
    locales:
      - language_tag: en-US
        offline_resources_path:
          - common/messages.properties
      - language_tag: de
        offline_resources_path:
          - common/messages_de.json
      - language_tag: fr
        offline_resources_path:
          - common/messages_fr.json
  - name: contact
    locales:
      - language_tag: en-US
        offline_resources_path:
          - contact/messages.properties
      - language_tag: de
        offline_resources_path:
          - contact/messages_de.json
      - language_tag: fr
        offline_resources_path:
          - contact/messages_fr.json

• Example of component definition in concise way

locales:
  - language_tag: en-US
    offline_resources_path:
      - $COMPONENT/messages.properties
  - language_tag: de
  - language_tag: fr

component_template:
  locales_refer: locales
  offline_resources_path:
    - $COMPONENT/messages_$LOCALE.json

components:
  - name: about
    template: component_template # default
  - name: common
  - name: contact

APIs Available

• Entry of library
  • I18N
• Interface For Release
  • Release
• Interface For Configuration
  • Config
• Interface For Translation
  • Translation

Entry of library

I18N

• It’s the entry code that creates and initializes the configuration object and the release object.

def add_config_file(config_file, outside_config=None)
def add_config(base_path, config_data)
def set_current_locale(locale)
def get_current_locale()
def get_release(product, version)

I18N / add_config_file

• Load a configuration json or yaml file and initialize a corresponding release object.

I18N / add_config

• Load a configuration json or yaml text with a base directory and initialize a correspondent release object.

I18N / set_current_locale

• Set locale of current thread.

I18N / get_current_locale

• Get locale of current thread.

I18N / get_release

• Get release object.

Interface For Release

Release

class Release:
    def get_config(self)
    def get_translation(self)
    def set_logger(self, logger)

Release / get_config

• Get the configuration object owned by the release object.

Release / get_translation

• Get the translation object owned by the release object.

Release / set_logger

• Set customized logger to the release object for it to use.

Interface For Configuration

Config

class Config:
    def get_config_data(self)
    def get_info(self)

Config / get_config_data

• Get configuration data.

Config / get_info

• Get brief information of configuration.

{
  "product": "PYTHON1",
  "version": "1.0.0",
  "remote": null,
  "local": "/tmp/data/l10n",
  "pseudo": true,
  "source_locale": "en-US",
  "default_locale": "en-US"
}

Interface For Translation

Translation

class Translation:
    def get_string(self, component, key, **kwargs)
    def get_locale_strings(self, locale)
    def get_locale_supported(self, locale)
    def format(self, locale, text, array)
    def get_locales(self, display_locale=None)

Translation / get_string

• Get the translation message of a component and a key.

• kwargs

• Examples of string formatting which follow the python format function when ‘format’ in configuration is set to ‘default’.

msg = trans.get_string(COMPONENT, KEY) => 'AAA{0}BBB{1}CCC'
msg = trans.get_string(COMPONENT, KEY, format_items = ['11', '22']) => 'AAA11BBB22CCC'

msg = trans.get_string(COMPONENT, KEY) => 'AAA{x}BBB{y}CCC'
msg = trans.get_string(COMPONENT, KEY, format_items = {'x': 'ee', 'y': 'ff'}) => 'AAAeeBBBffCCC'

• Example which follows the rules of CLDR MessageFormat when ‘format’ in configuration is set to ‘icu’.

msg = trans.get_string(COMPONENT, KEY, locale = 'en-US', format_items = [1, 7])
# COMPONENT, KEY => I bought {0, plural, one {# book} other {# books}} and {1, plural, one {# cup} other {# cups}}.
# msg => I bought 1 book and 7 cups.

Translation / get_locale_strings

• Get translation messages of a locale.

Translation / get_locale_supported

• Get supported locale name of the input locale.

Translation / format

• Get the formatted string by given locale, format text and arguments.

• Example which follows the rules of CLDR MessageFormat when ‘format’ in configuration is set to ‘icu’.

msg = trans.format('en', 'I bought {0, plural, one {# book} other {# books}}.', [1])

• When ‘format’ in configuration is set to ‘default’, its format string follows the python format function.

Translation / get_locales

• Get information of locales being used.

{
  "en-US": {
    "as": "source",
    "from": "local",
    "display": "英语（美国）"
  },
  "de": {
    "from": "remote",
    "display": "德语"
  }
}

Interface For Logger

Logger

class Logger:
    def log(self, text, log_type)

Translation / log

• Log text with type of log_type.