Skip to end of metadata
Go to start of metadata

Zend Framework: Zend_Controller_Router_Route_Translatable Component Proposal

Proposed Component Name Zend_Controller_Router_Route_Translatable
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Controller_Router_Route_Translatable
Proposers Ben Scholzen
Zend Liaison Matthew Weier O'Phinney
Revision 1.0 - 2 March 2009: Initial Draft. (wiki revision: 8)

Table of Contents

1. Overview

Zend_Controller_Router_Route_Translatable allows translation of fixed texts as well as an enumeration of parameters within URLs. The route basically works like the standard route.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • This component will allow translation of fixed texts
  • This component will allow translation of enumerated parameters
  • This component will not need a change of the way a user assembles the route or gets the parameters.
  • This component will allow one-time-locales for translations into a different language than the current one.

4. Dependencies on Other Framework Components

  • Zend_Translate
  • Zend_Controller_Router_Route

5. Theory of Operation

Initialisation of the Route
To be able to use the route, it requires an instance of Zend_Translate. You can either set it via the the static class method:

If the instance was not set via this method, the route looks for an instance in Zend_Registry with the key 'Zend_Translate'. If that one isn't set either, it will throw an exception.

Zend_Translate should be an instance, which already has the current locale set. After that you can simply use the route like any other.

Route definition
The route itself works like the usual Zend_Controller_Router_Route, as it separates the parameters with a slash by default. To insert a fixed translatable text, you simply write @foobar, where foobar is the message-id. For inserting a translatable parameter, you write :@foobar.

One-Time-Locale
Sometimes you need to create a route, which is translated into another language as the the one, for example when you have a language-switch link which should directly go to the same route again. In this case you call

right before you assemble the route.

6. Milestones / Tasks

  • Milestone 1: Community reviews collected
  • Milestone 2: Prototype finalized and checked into SVN
  • Milestone 3: Unit tests exist, work, and are checked into SVN.
  • Milestone 4: Initial documentation exists.

7. Class Index

  • Zend_Controller_Router_Route_Translatable

8. Use Cases

UC-01
UC-02
UC-03
UC-04

9. Class Skeletons

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

8 Comments

comments.show.hide

  1. Mar 07, 2009

    Ben Scholzen

    No response after a week on the info in the mailing list. Moving on to ready for recommendation.

  2. Mar 11, 2009

    Jens Kleikamp

    Great proposal!
    As today we use this router in production with zf, it works flawlessly.

    Thanks Ben!

  3. Mar 16, 2009

    Jan Sorgalla

    Absolutely useful addition. Used a similar class for many multilingual projects.

    What i would see (in addition to setOneTimeLocale()) is something like a pushLocale()/restoreLocale() pair.

    I often have to render views (ie. mail bodies) which contain a few urls generated with $this->url().

    So

    would be useful.

  4. Mar 22, 2009

    Robin Skoglund

    Let's not use static methods for non-static things.

    The outlined solution for switching languages (one-time locale, UC-02) is cumbersome to use, and is basically procedural programming. It should be possible to specify the locale to use per route. An idea for how to solve this; add a reseverd word to routes, e.g. '$locale', which would be used when assembling URIs. I'm not exactly sure how this would be implemented, but I imagine using it something like this:

  5. Mar 22, 2009

    Robin Skoglund

    Just another note.

    Imo it should also be possible to sniff out locale from a matched route. E.g. when a user opens http://site.example.com/user/50/edit an English page will be shown, and http://site.example.com/benutzer/50/redigieren would show a German page. This implies that the locale is given in the matched route, and is used when setting up Zend_Translate.

    1. Mar 22, 2009

      Ben Scholzen

      Tho this is a complete different behaviour. This route is intended to match in the current locale. You behaviour would need to have the route check all defined locales, so this should be an option, not the default behaviour. The question is, how to tell all translatable routes to act like this and how to tell then, which locales to check. Giving those information to every single translatable route is a bit awkward, so a static method is actually the way to solve this. Comments?

  6. Mar 27, 2009

    Matthew Weier O'Phinney

    Zend Acceptance
    This proposal is accepted for immediate development in the standard incubator, with the following revisions:
    • Rename to Zend_Controller_Router_Route_Translated
    • Translator dependency:
      • Rename setTranslate() to setTranslator() for consistency with other components
      • setTranslate() should be an instance method, not static
      • Add a static setDefaultTranslator() method
      • Make sure getTranslator() follows the following algorithm:
        • check for specific object registered with this instance
        • then check for default translator registered statically
        • then check for Zend_Translate key in Zend_Registry
        • Throw exception if none of the above work
    • Locale dependency:
      • Remove setOneTimeLocale
      • Add instance method setLocale() and static method setDefaultLocale()
      • Have getLocale() work like getTranslator()
    • Allow passing Translator and Locale objects to constructor via options
    • assemble() method should allow specifying a @locale key to override the current locale when assembling a URL

  7. Apr 01, 2009

    Ben Scholzen

    Translated route is now part of the standard route.