[Zope-Checkins] CVS: Zope3/lib/python/Zope/I18n - ITranslationService.py:1.3

[Barry Warsaw]

Update of /cvs-repository/Zope3/lib/python/Zope/I18n
In directory cvs.zope.org:/tmp/cvs-serv18051/lib/python/Zope/I18n

Modified Files:
	ITranslationService.py 
Log Message:
Comment cleanup.

Also changed translate(..., source, ...) to translate(..., msgid, ...)
for consistency.


=== Zope3/lib/python/Zope/I18n/ITranslationService.py 1.2 => 1.3 ===
 
 class ITranslationService(Interface):
-    """Translation Service
+    """The Translation Service
 
-    This interface provides methods for translating text, including
-    text with interpolation.
+    This interface provides methods for translating text, including text with
+    interpolation.
 
-    When we refer to text here, we mean text that follows the standard
-    Zope 3 text representation.
+    When we refer to text here, we mean text that follows the standard Zope 3
+    text representation.
 
-    Standard arguments:
+    Standard arguments in the methods described below:
 
         domain -- The domain is used to specify which translation to use.
                   Different products will often use a specific domain naming
                   translations supplied with the product.
-                  Stephan's (my) favorite example is: How do you translate
-                  "Sun"? Is it our star, the abbreviation of Sunday or the
-                  company? Specifying the domain, such as "Stars" will solve
-                  this problem for us.
 
-        source -- The source message or message id that should be translated.
+                  A favorite example is: How do you translate "Sun"?  Is it
+                  our star, the abbreviation of Sunday or the company?
+                  Specifying the domain, such as "Stars" or "DaysOfWeek" will
+                  solve this problem for us.
+
+        msgid -- The id of the message that should be translated.  This may be
+                 an implicit or an explicit message id.
 
         mapping -- The object to get the interpolation data from.
 
         target_language -- The language to translate to.
 
         context -- An object that provides contextual information for
-                   determining client language preferences. It must
-                   implement or have an adapter that implements
-                   IUserPreferedLanguages.
+                   determining client language preferences.  It must implement
+                   or have an adapter that implements IUserPreferredLanguages.
 
-        Note that one of destination_language or context must be
-        passed. Otherwise a TypeError will be raised.
+        Note that one of target_language or context must be passed.  Otherwise
+        a TypeError will be raised.
 
         Also note that language tags are defined by RFC 1766.
     """
 
-
-    def translate(domain, source, mapping=None, 
+    def translate(domain, msgid, mapping=None, 
                   context=None, target_language=None):
-        """Translate source text. Translated text is returned.
+        """Return the translation for the message referred to by msgid.
 
-           However, the method does a little more than a vanilla
-           translation. The method also looks for a possible language to
-           translate to.
-           After a translation it also replaces any variables inside the 
+           However, the method does a little more than a vanilla translation.
+           The method also looks for a possible language to translate to.
+           After a translation it also replaces any $name variable variables
+           inside the post-translation string.
            
            Note: The TranslationService interface does not support simplified
                  translation methods, since it is totally hidden by ZPT and in
@@ -71,7 +71,8 @@
                  the simplifications.
         """
 
-
     def getDomain(domain):
-        """Get the domain for the passed domain name"""
-        
+        """Get the domain for the passed domain name.
+
+        The domain supports the IDomain interface
+        """