You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by mg...@apache.org on 2015/12/25 14:08:57 UTC

[42/50] isis git commit: ISIS-1093: updating docs for i18n support for Wicket viewer.

ISIS-1093: updating docs for i18n support for Wicket viewer.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/ef96cc80
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/ef96cc80
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/ef96cc80

Branch: refs/heads/ISIS-1223-upgrade-to-wicket-7
Commit: ef96cc80fe89290d2be79f831eb354dc0d7f886c
Parents: 493d31b
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Dec 23 12:49:07 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Dec 23 12:49:07 2015 +0000

----------------------------------------------------------------------
 .../src/main/asciidoc/documentation.adoc        |   1 -
 .../src/main/asciidoc/guides/_ugbtb_i18n.adoc   | 265 ++++++++++++++++++-
 .../src/main/webapp/WEB-INF/translations-en.po  |   7 +-
 .../src/main/webapp/WEB-INF/translations-es.po  |   7 +-
 .../src/main/webapp/WEB-INF/translations-nl.po  |   7 +-
 .../src/main/webapp/WEB-INF/translations.po     |   9 +-
 6 files changed, 266 insertions(+), 30 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/ef96cc80/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index fcfb767b..6df54b8 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -120,7 +120,6 @@ tools (not ASF):
 * link:./articles-and-presentations.html[Articles, Conferences, Podcasts]
 * link:./books.html[Books]
 * link:./resources/thesis/Pawson-Naked-Objects-thesis.pdf[Naked Objects PhD thesis] (Pawson)
-* link:https://github.com/isisaddons/isis-app-simpledsl/[isis-script DSL]
 //* link:./downloadable-presentations.html[Downloadable Presentations]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/ef96cc80/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc
index e63293c..bc126c4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc
@@ -5,17 +5,19 @@
 :_imagesdir: images/
 
 
-Apache Isis' support for i18n allows every element of the domain model (the class names, property names, action names, parameter names and so forth) to be translated.
+Apache Isis' support for internationlization (i18n) allows every element of the domain model (the class names, property names, action names, parameter names and so forth) to be translated.
 
 It also supports translations of messages raised imperatively, by which we mean as the result of a call to `title()` to obtain an object's title, or messages resulting from any business rule violations (eg xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], and so on.
 
-Isis does not translate the values of your domain objects, though.  So, if you have a domain concept such as `Country` whose name is intended to be localized according to the current user, you will need to model
+(As of `1.11.0-SNAPSHOT`), the xref:ugvw.adoc#[Wicket viewer] (that is, its labels and messages) is also internationalized using the same mechanism.  If no translations are available, then the Wicket viewer falls back to using Wicket resource bundles.
+
+Isis does not translate the values of your domain objects, though.  So, if you have a domain concept such as `Country` whose name is intended to be localized according to the current user, you will need to model this yourself.
 
 
 
 == Implementation Approach
 
-Most Java frameworks tackle i18n by using Java's own `ResourceBundle` API.  However, there are some serious drawbacks in this approach, such as:
+Most Java frameworks tackle i18n by using Java's own `ResourceBundle` API.  However, there are some serious drawbacks in this approach, including:
 
 * if a string appears more than once (eg "name" or "description") then it must be translated everywhere it appears in every resource bundle file
 * there is no support for plural forms (see this link:http://stackoverflow.com/questions/14326653/java-internationalization-i18n-with-proper-plurals/14327683#14327683[SO answer])
@@ -32,7 +34,7 @@ The format of the `.pot` and `.po` files is identical; the only difference is th
 
 [IMPORTANT]
 ====
-Although Apache Isis' implementation is modelled after GNU's API, it does _not_ use any GNU software.  This is for two reasons: (a) to simplify the toolchain/developer experience, and (b) because GNU software is usually GPL, which would be incompatible with the Apache license).
+Although Apache Isis' implementation is modelled after GNU's API, it does _not_ use any GNU software.  This is for two reasons: (a) to simplify the toolchain/developer experience, and (b) because GNU software is usually GPL, which would be incompatible with the Apache license.
 ====
 
 This design tackles all the issues of ``ResourceBundle``s:
@@ -214,6 +216,261 @@ public interface TranslatableException {
 
 
 
+
+
+== Wicket Viewer (`1.11.0-SNAPSHOT`)
+
+(As of `1.11.0-SNAPSHOT`), the xref:ugvw.adoc#[Wicket viewer] (its labels and messages) is also internationalized using
+the `TranslationService`.  This is done through an Isis-specific implementation of the Wicket framework's `org.apache.wicket.Localizer` class, namely `LocalizerForIsis`.
+
+The Wicket `Localizer` defines the following API:
+
+[source,java]
+----
+public String getString(
+        final String key,               // <1>
+        final Component component,      // <2>
+        final IModel<?> model,
+        final Locale locale,
+        final String style,
+        final String defaultValue)
+    throws MissingResourceException { ... }
+----
+<1> The key to obtain the resource for
+<2> The component to get the resource for (if any)
+
+For example, `key` might be a value such as "okLabel", while `component` an internal class of the Wicket viewer, such as `EntityPropertiesForm`.
+
+The `LocalizerForIsis` implementation uses the `key` as the `msgId`, while the fully qualified class name of the
+`component` is used as a context.  There is one exception to this: if the component is the third-party select2
+component (used for drop-downs), then that class name is used directly.
+
+In the main, using Isis' i18n support means simply adding the appropriate translations to the `translation.po` file,
+for each locale that you require.  If the translations are missing then the original translations from the Wicket
+resource bundles will be used instead.
+
+=== Commonly used
+
+Most of the translation requirements can be covered by adding in the following ``msgId``s:
+
+[source,properties]
+----
+#: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
+msgid "CollectionContentsAsAjaxTablePanelFactory.Table"
+msgstr "Table"
+
+#: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
+msgid "CollectionContentsAsUnresolvedPanel.Hide"
+msgstr "Hide"
+
+#: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
+msgid "aboutLabel"
+msgstr "About"
+
+#: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
+msgid "cancelLabel"
+msgstr "Cancel"
+
+#: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
+msgid "datatable.no-records-found"
+msgstr "No Records Found"
+
+#: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
+msgid "editLabel"
+msgstr "Edit"
+
+#: org.wicketstuff.select2.Select2Choice
+msgid "inputTooShortPlural"
+msgstr "Please enter {number} more characters"
+
+#: org.wicketstuff.select2.Select2Choice
+msgid "inputTooShortSingular"
+msgstr "Please enter 1 more character"
+
+#: org.wicketstuff.select2.Select2Choice
+msgid "loadMore"
+msgstr "Load more"
+
+#: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
+msgid "logoutLabel"
+msgstr "Logout"
+
+#: org.wicketstuff.select2.Select2Choice
+msgid "noMatches"
+msgstr "No matches"
+
+#: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
+msgid "okLabel"
+msgstr "OK"
+
+#: org.wicketstuff.select2.Select2Choice
+msgid "searching"
+msgstr "Searching..."
+
+#: org.wicketstuff.select2.Select2Choice
+msgid "selectionTooBigPlural"
+msgstr "You can only select {limit} items"
+
+#: org.wicketstuff.select2.Select2Choice
+msgid "selectionTooBigSingular"
+msgstr "You can only select 1 item"
+----
+
+=== Login/self-sign-up
+
+In addition, there are a reasonably large number of messages that are used for both login and the
+ xref:ugvw.adoc#_ugvw_features_user-registration[user registration] (self sign-up) and password reset features.
+
+These are:
+
+[source,properties]
+----
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+msgid "AutoLabel.CSS.required"
+msgstr "Required"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "confirmPasswordLabel"
+msgstr "Confirm password"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+msgid "emailIsNotAvailable"
+msgstr "The given email is already in use"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "emailPlaceholder"
+msgstr "Enter your email"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+msgid "emailPlaceholder"
+msgstr "Enter an email for the new account"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "emailLabel"
+msgstr "Email"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "emailSentMessage"
+msgstr "An email has been sent to '${email}' for verification."
+
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+msgid "forgotPasswordLinkLabel"
+msgstr "Forgot your password?"
+
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+msgid "loginHeader"
+msgstr "Login"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "noSuchUserByEmail"
+msgstr "There is no account with this email"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "noUserForAnEmailValidToken"
+msgstr "The account seems to be either already deleted or has changed its email address. Please try again."
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "passwordChangeSuccessful"
+msgstr "The password has been changed successfully. You can <a class=\"alert-success\" style=\"text-decoration:underline;\" href=\"${signInUrl}\">login</a> now."
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "passwordChangeUnsuccessful"
+msgstr "There was a problem while updating the password. Please try again."
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "passwordLabel"
+msgstr "Password"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "passwordPlaceholder"
+msgstr "Enter password"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "passwordResetExpiredOrInvalidToken"
+msgstr "You are trying to reset the password for an expired or invalid token"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "passwordResetHeader"
+msgstr "Forgot password"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "passwordResetSubmitLabel"
+msgstr "Submit"
+
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+msgid "registerButtonLabel"
+msgstr "Register"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+msgid "registerHeader"
+msgstr "Register"
+
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+msgid "rememberMeLabel"
+msgstr "Remember Me"
+
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+msgid "resetButtonLabel"
+msgstr "Reset"
+
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+msgid "signInButtonLabel"
+msgstr "Sign in"
+
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+msgid "signUpButtonLabel"
+msgstr "Don't have an account? Sign up now."
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "signUpButtonLabel"
+msgstr "Verify email"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+msgid "signUpHeader"
+msgstr "Sign Up"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "usernameIsNotAvailable"
+msgstr "The provided username is already in use"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "usernameLabel"
+msgstr "Username"
+
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.signup.RegistrationFormPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.register.RegisterPage
+#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
+#: org.apache.isis.viewer.wicket.ui.pages.accmngt.password_reset.PasswordResetPage
+msgid "usernamePlaceholder"
+msgstr "Username"
+----
+
+
+
+
+
+
 == Integration Testing
 
 So much for the API; but as noted, it is also necessary to ensure that the required translations are recorded (by the `TranslationService`) into the `.pot` file.

http://git-wip-us.apache.org/repos/asf/isis/blob/ef96cc80/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-en.po
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-en.po b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-en.po
index 2bc2242..6daefe7 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-en.po
+++ b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-en.po
@@ -312,7 +312,7 @@ msgstr "YAML"
 
 #: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
 msgid "aboutLabel"
-msgstr ""
+msgstr "About"
 
 
 #: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
@@ -505,11 +505,6 @@ msgstr "Sign in"
 
 
 #: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
-msgid "signInFailed"
-msgstr ""
-
-
-#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
 msgid "signUpButtonLabel"
 msgstr "Don't have an account? Sign up now."
 

http://git-wip-us.apache.org/repos/asf/isis/blob/ef96cc80/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-es.po
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-es.po b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-es.po
index 3107a32..fab4c95 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-es.po
+++ b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-es.po
@@ -311,7 +311,7 @@ msgstr "YAML"
 
 #: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
 msgid "aboutLabel"
-msgstr ""
+msgstr "About"
 
 
 #: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
@@ -504,11 +504,6 @@ msgstr "Sign in"
 
 
 #: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
-msgid "signInFailed"
-msgstr ""
-
-
-#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
 msgid "signUpButtonLabel"
 msgstr "Don't have an account? Sign up now."
 

http://git-wip-us.apache.org/repos/asf/isis/blob/ef96cc80/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-nl.po
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-nl.po b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-nl.po
index d497b8c..1da75b7 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-nl.po
+++ b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations-nl.po
@@ -313,7 +313,7 @@ msgstr "YAML"
 
 #: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
 msgid "aboutLabel"
-msgstr ""
+msgstr "About"
 
 
 #: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
@@ -506,11 +506,6 @@ msgstr "Sign in"
 
 
 #: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
-msgid "signInFailed"
-msgstr ""
-
-
-#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
 msgid "signUpButtonLabel"
 msgstr "Don't have an account? Sign up now."
 

http://git-wip-us.apache.org/repos/asf/isis/blob/ef96cc80/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations.po
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations.po b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations.po
index fd1127a..6643591 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations.po
+++ b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/translations.po
@@ -34,7 +34,7 @@ msgstr ""
 
 #: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
 msgid "AutoLabel.CSS.required"
-msgstr ""
+msgstr "Required"
 
 
 #: org.apache.isis.core.runtime.system.IsisSystem
@@ -312,7 +312,7 @@ msgstr "YAML"
 
 #: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
 msgid "aboutLabel"
-msgstr ""
+msgstr "About"
 
 
 #: org.apache.isis.viewer.wicket.ui.pages.entity.EntityPage
@@ -505,11 +505,6 @@ msgstr "Sign in"
 
 
 #: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
-msgid "signInFailed"
-msgstr ""
-
-
-#: org.apache.isis.viewer.wicket.ui.pages.login.WicketSignInPage
 msgid "signUpButtonLabel"
 msgstr "Don't have an account? Sign up now."