r9 - 17 Aug 2006 - 11:55:18 - MarkkuMielityinenYou are here: OSAF >  Projects Web  >  DevelopmentHome > InternationalizationProject > ChandlerInternationalizationPrototype

Preface

This prototype has been used by Brian Kirsch in development of EggTranslations package, which is now officially a part of Chandler. The information presented in this document is now partially outdated and developers should refer to the official 0.7 roadmap, proposal, discussions, and EggTranslations README.

Table of Contents


Related documentation

Internal

  1. chandler/projects/Chandler-FeedsPlugin/
  2. http://leilani.osafoundation.org/~bkirsch/i18n/ChandlerInternationalizationProposal.html
  3. http://leilani.osafoundation.org/~bkirsch/i18n/busydev.html

External

  1. http://peak.telecommunity.com/DevCenter/PythonEggs
  2. http://peak.telecommunity.com/DevCenter/EasyInstall
  3. http://peak.telecommunity.com/DevCenter/setuptools
  4. http://peak.telecommunity.com/DevCenter/PkgResources


Documentation for a python egg based resource management system (RMS)

Building a RMS resource egg

  1. Creating a new python egg
    1. Create a project directory:
      # create a new project directory for myresproj project
      mkdir myresproj
      svn add myresproj
      cd myresproj
    2. Copy ez_setup.py and setup.py files to your project directory:
      # copy project files
      cp ~/ez_setup.py .
      svn add ez_setup.py
      cp ~/setup.py .
      svn add setup.py
    3. Edit the setup.py file to meet your project needs:
      #!/bin/env python
      # -*- coding: utf-8 -*-

      # Copyright (c) 2003-2006 Open Source Applications Foundation
      #
      # Licensed under the Apache License, Version 2.0 (the "License");
      # you may not use this file except in compliance with the License.
      # You may obtain a copy of the License at
      #
      # http://www.apache.org/licenses/LICENSE-2.0
      #
      # Unless required by applicable law or agreed to in writing, software
      # distributed under the License is distributed on an "AS IS" BASIS,
      # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      # See the License for the specific language governing permissions and
      # limitations under the License.

      """
      myresproj setup
      """

      @author
      Your name - Your email
      @copyright
      Copyright (c) 2003-2006 Open Source Applications Foundation
      @license
      Apache License, Version 2.0
      # make sure that we have easy setup tools
      import ez_setup
      ez_setup.use_setuptools()

      # import packages
      from setuptools import setup

      # the setup block
      setup(
      # package description
      name = "myresproj",
      version = "0.1",
      author = "your name",
      author_email = "your email",
      maintainer = "your name",
      maintainer_email = "your email",
      url = "the project homepage",
      download_url = "the project homepage",
      description = "description of this package",
      long_description = "longer description of this package",
      keywords = "myresproj egg_i18n",
      license = "Apache License, Version 2.0",
      classifiers=[
      # use these as needed #"Development Status :: 4 - Beta",
      #"Environment :: GUI",
      #"Environment :: Web Environment",
      #"Intended Audience :: End Users/Desktop",
      #"Intended Audience :: Developers",
      #"Intended Audience :: System Administrators",
      #"License :: OSI Approved :: Python Software Foundation License",
      #"Operating System :: MacOS :: MacOS X",
      #"Operating System :: Microsoft :: Windows",
      #"Operating System :: POSIX",
      #"Programming Language :: Python",
      #"Topic :: Communications :: Email",
      #"Topic :: Office/Business",
      #"Topic :: Software Development :: Bug Tracking",
      ],

      # package contents
      )
    4. Generate an egg project structure:
      # generate an egg structure
      python setup.py bdist_egg
  2. Copying files to the resource
    Copy all your resource files to [project name].egg-info/ directory. If you want, you can use subdirectories under the [project name].egg-info/ directory to organize your files.
    # copy files
    mkdir myresproj.egg-info/images
    cp .../myimage.jpg myresproj.egg-info/images/
    svn add myresproj.egg-info/images/myimage.jpg
    cp .../mypage.html myresproj.egg-info/
    svn add myresproj.egg-info/mypage.html
    cp .../mypanel.xrc myresproj.egg-info/
    svn add myresproj.egg-info/mypanel.xrc
    cp .../gettext.mo myresproj.egg-info/
    svn add myresproj.egg-info/gettext.mo
  3. Writing a resource manifest file
    Create/edit [project name].egg-info/[project name]_resource.info file using your favourite text editor. This file uses the common INI file structure with the exception that comments are marked with '#' character. A header consists of two parts
    [myapp::all]
    myimage.jpg=images/myimage.jpg
    mypage.html=mypage.html
    mypanel.xrc=mypanel.xrc
    [myapp::fi]
    gettext.mo=gettext.mo
  4. Building, installing, and distributing resource eggs
    # this is how you build an egg when you are developing
    python setup.py develop
    # this is how you build an egg for distribution.
    # your egg file will be placed in dist/ directory.
    python setup.py install

The RMS application programming interface (API)

def HasNonlocalizedResource(project, name):
"""
Check if RMS has the requested nonlocalized resource.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: boolean
@return: do we have this resource
"""

def HasLocalizedResource(project, name):
"""
Check if RMS has the requested localized resource.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: boolean
@return: do we have this resource
"""

def IsNonlocalizedDir(project, name):
"""
Check if the named RMS nonlocalized resource is a directory.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: boolean
@return: do we have this directory
"""

def IsLocalizedDir(project, name):
"""
Check if the named RMS localized resource is a directory.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: boolean
@return: do we have this directory
"""

def ListNonlocalizedDir(project, name):
"""
List the named RMS nonlocalized resource directory contents.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: list of strings
@rparam: the contents of the directory
"""

def ListLocalizedDir(project, name):
"""
List the named RMS localized resource directory contents.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: list of strings
@rparam: the contents of the directory
"""

def GetNonlocalizedStream(project, name):
"""
Read the named RMS nonlocalized resource as a stream.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: stream
@rparam: the resource data
"""

def GetLocalizedStream(project, name):
"""
Read the named RMS localized resource as a stream.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: stream
@rparam: the resource data
"""

def GetNonlocalizedString(project, name):
"""
Read the named RMS nonlocalized resource as a string.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: string
@rparam: the resource data
"""

def GetLocalizedString(project, name):
"""
Read the named RMS localized resource as a string.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: string
@rparam: the resource data
"""

def GetNonlocalizedLines(project, name):
"""
Read the named RMS nonlocalized resource as a list of strings.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: list of strings
@return: the resource data
"""

def GetLocalizedLines(project, name):
"""
Read the named RMS localized resource as a list of strings.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@rtype: list of strings
@return: the resource data
"""

def RunNonlocalizedScript(project, name, namespace):
"""
Execute the named RMS nonlocalized resource.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@type namespace: dictionary
@param namespace: namespace (i.e. module dictionary)

@rtype: none
@return: -
"""

def RunLocalizedScript(project, name, namespace):
"""
Execute the named RMS localized resource.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@type namespace: dictionary
@param namespace: namespace (i.e. module dictionary)

@rtype: none
@return: -
"""

def GetNonlocalizedText(project, name, str):
"""
Translate a string using the named RMS nonlocalized resource.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@type str: string
@param str: the string to be translated

@rtype: unicode
@return: the translated string
"""

def GetLocalizedText(project, name, str):
"""
Translate a string using the named RMS localized resource.

@type project: string
@param project: project name (equal to domain)

@type name: string
@param name: resource name

@type str: string
@param str: the string to be translated

@rtype: unicode
@return: the translated string
"""

def SetResourceLocale(locale):
"""
Check if RMS has the requested nonlocalized resource.

@type locale: string/list
@param locale: commaseparated stringlist of locale codes or a list of locale codes

@rtype: none
@rparam: -
"""

Using the RMS in your own projects

  1. Copy egg_i18n.py to your project directory
    # copy RMS API to your project folder
    cp .../egg_i18n.py .
    svn add egg_i18n.py
  2. (Optional) if you are developing an egg, include the egg_i18n.py module in your setup.py list of modules Add "egg_i18n" to your py_modules variable.
    ...
    # package contents
    py_modules = ["myapp","egg_i18n"],
    ...
  3. Introducing RMS services to your python module
    Place the following code in the beginning of all of your python modules that require RMS services:
    #===============================================================================
    # ACCESS TO RESOURCES
    #===============================================================================

    from egg_i18n import *

    def _T(str): return GetNonlocalizedText("myapp", None, str)
    def _(str): return GetLocalizedText("myapp", "gettext.mo", str)
  4. Setting the current locale
    # set the default locale (empty locale or no locale)
    SetLocale("")
    # set locale to fi
    SetLocale("fi")
    # set locale to fr and use locale fi as a fallback locale
    SetLocale("fr,fi")
  5. Using RMS services in your python module
    The following code gives examples on how to load images, HTML pages, XRC panels, and translated texts from the RMS.
    ...
    # load a bitmap from a resource stream
    bitmap = wx.ImageFromStream(GetLocalizedStream("myapp","myimage.jpg"),wx.BITMAP_TYPE_JPEG).ConvertToBitmap()
    bmppanel = wx.Panel(...)
    bmppanel.bmp = wx.StaticBitmap(parent=bmppanel, bitmap=bitmap)
    self.Add(bmppanel, 0, wx.GROW|wx.ALL, 5)
    ...

    ...
    # load a HTML page from localres file server
    htmlpanel = wx.html.HtmlWindow(...)
    htmlpanel.LoadPage(u"myapp#localres:mypage.html")
    self.Add(htmlpanel, 0, wx.GROW|wx.ALL, 5)
    ...

    ...
    # load an XRC panel from localres file server
    xrcresources = wx.xrc.XmlResource(u"myapp#localres:mypanel.xrc")
    xrcpanel = self.xrcresources.LoadPanel(self, u"PANEL")
    self.Add(self.xrcpanel, 0, wx.GROW|wx.ALL, 5)
    ...

    ...
    # examples of translated and untranslated strings
    SetHelpText(_T("nonlocalized text")) # here "nonlocalized text" will not be translated.
    SetHelpText(_("localized text")) # here "localized text" will be translated to a local language if approapriate gettext.mo resource is available.
    ...


Testing of the python egg based resource management system (RMS)

  1. Check your python installation:
    1. You need to have python version 2.4 or later to run the demo.
    2. You need to have a resent version of wxPython installed.
      • The version that is suggested by the (breezy) Ubuntu package manager is not resent enough.
    3. If you are using Ubuntu Linux, you need to have version dapper or later to run the demo.
  2. Create a working directory where you can download and run files.
  3. Install EasyInstall :
    1. Download ez_setup.py from http://peak.telecommunity.com/DevCenter/EasyInstall.
    2. Install setuptools:
      • If you have python and python tools in your PATH environment variable:
        # install setuptools
        ./ez_setup.py setuptools==dev
      • Otherwise:
        # install setuptools
        python ./ez_setup.py setuptools==dev
      • The development version is needed to obtain a few necessary bugfixes
      • You may also not have the relevant privileges to run this command, in which case, try to run it in su mode:
        # install setuptools
        sudo ./ez_setup.py setuptools==dev
        # install setuptools
        sudo python ./ez_setup.py setuptools==dev
  4. Download two egg files:
    1. mmmmdemo-0.1-py2.4.egg
    2. mmmmdemo_moreres-0.1-py2.4.egg
  5. Install the two egg files:
    • If you have python and python tools in your PATH environment variable:
      # install mmmmdemo-0.1-py2.4.egg
      easy_install mmmmdemo-0.1-py2.4.egg
      # install mmmmdemo_moreres-0.1-py2.4.egg
      easy_install mmmmdemo_moreres-0.1-py2.4.egg
    • Otherwise:
      # install mmmmdemo-0.1-py2.4.egg
      python ez_setup.py mmmmdemo-0.1-py2.4.egg
      # install mmmmdemo_moreres-0.1-py2.4.egg
      python ez_setup.py mmmmdemo_moreres-0.1-py2.4.egg
  6. Play with the demo:
    • If you have python and python tools in your PATH environment variable:
      # run in default locale
      mmmmdemo
      # run in en_US locale
      mmmmdemo -l en_US
      # run in fi locale
      mmmmdemo -l fi
      # run in fr locale and use fi locale as a fallback locale
      mmmmdemo -l fr,fi
    • Otherwise:
      # run in default locale
      python -c "from mmmmdemo import main; main([])"
      # run in en_US locale
      python -c "from mmmmdemo import main; main(['-l','en_US'])
      # run in fi locale
      python -c "from mmmmdemo import main; main(['-l','fi'])
      # run in fr locale and use fi locale as a fallback locale
      python -c "from mmmmdemo import main; main(['-l','fr,fi'])
  7. Report your successes, failures, and ideas to mmmm@osafoundation.org.


-- MarkkuMielityinen - 09 Jun 2006

Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r9 < r8 < r7 < r6 < r5 | More topic actions
 
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.