System Defined Translations using Ecollect-TranslationManager Plugin

Ecollect Forms and Enrollment Express provide a plugin that simplifies the translation of forms into multiple languages. Districts in non-English speaking countries can now translate all system-defined content within the products. After translations are added and enabled, the product will be displayed in the user's login language.

The Ecollect-TranslationManager plugin facilitates translations using property files. This plugin includes a template property file that can be updated with translations in the desired language.

Furthermore, the translation plugin enables the repurposing of existing fields by renaming the labels to suit your school or district's unique needs.

Access to localization tools is based on group security permissions and can be accomplished either in a batch process or on a page-by-page basis, providing flexibility for your localization workflow.

Prerequisite

Configure necessary locales in SIS

PowerSchool SIS has the required locales configured on the Manage Locales page (navigate to System Administrator, click Page and Data Management, and then select Manage System Locales). Review the Manage System Locales section for guidance with locale setup.

The translation of system-defined content, including date/time formats and UI orientation, depends on the language settings configured in the Manage System Locales page. When you log in to SIS and choose a specific language, all the system-defined content for Ecollect Forms/Enrollment Express be automatically translated into that selected language, also the other settings such as date/time format and UI orientation will be aligned with the chosen language preferences.

Configure necessary languages in Form Configurations

Ensure that the essential languages are set up in Forms configuration (navigate to System Administrator, click Forms, and then select Configure Form Languages).

The translation of all the dynamic form content will depend on language settings made on this page. Things to note:

• Ensure that the languages especially the default language on the Manage System Locales page and Configure Form Languages page are identical.

• If you make changes to language setup including changing the default language, ensure that the same change is made on both the pages.

Add Translations on All System-defined Content

Administrators can add translations to all system-defined content, such as form list tab headers, form tab names, submit buttons, and more, using the Ecollect-TranslationManager plugin. These translations are supported across the Parent/Student portal, Pre-Registration form, Teacher portal, and Administrator portal.

To enable the Ecollect-TranslationManager plugin, administrators must follow these steps:

1. Download the Ecollect-TranslationManager plugin.

2. Extract the content to view the property files.

3. Create a copy of the template property files and edit them to add translations.

4. Save and rename the property files based on Country and Language combinations.

5. Build the plugin with the translated property files.

6. Install and enable the Ecollect-TranslationManager plugin.

Download the Ecollect-TranslationManager Plugin

Upon each release, this plugin and instructions will be available on PowerSchool Community.

1. Download the Ecollect-TranslationManager plugin.  

2. Extract the content to view the property files.

3. Navigate to the MessageKeys folder within the plugin.

   

4. Open the folder to view the template properties files.

   

Update the Translations

Create a copy of the template property files and open them to update with your translations. Open to view the property of each file.

• eec_admin_template.US_en.properties

  • The file contains content from the admin portal, and some cross-portal texts relevant to the guardian and teacher portals.

• eec_parent_template.US_en.properties

  • The file contains content from the guardian portal, which is for both parent and student access.

• eec_pre-registration_template.US_en.properties

  • The file contains content from the pre-registration page.

  • It is relevant only if you are an Enrollment Express customer.

  • If you are not an Enrollment Express customer, you can delete this file as it does not require translation.

• eec_teacher_template.US_en.properties

  • The file contains content from the teacher portal page.

  • Update the English text with your translations corresponding to each of the message keys.

  • The English system-defined text to the right of the equals sign (=) is to be translated. For example:

    • eec.js.scripts_formbuilder_js.main.swal_ok=OK

    • eec.js.scripts_formbuilder_js.main.swal_cancel=Cancel

    • eec.js.scripts_formbuilder_js.main.swal_successtitle=Thank You!

    • eec.js.scripts_formbuilder_js.main.swal_errortitle=Form Error

    • eec.js.scripts_formbuilder_js.main.swal_warningtitle=Warning

  • The content on the left side of the equal sign ('=') is the Message Key and it should not be changed.

  • Do not add additional spaces between message key and the translations. Including extra spaces can cause the translated messages to not show up on the UI.

Complete this process for translations in as many languages as required. If you have translations for multiple languages, follow the following steps for each language.

Note:

• Only one plugin is permitted, with multiple locale translation files within it.

• Dynamic form content on the form such as element titles, descriptions, and more, should have translations added by the user as before and they also continue to use EEC languages as setup in the Configure Form Languages page (EEC Forms Configuration).

• The Open Language options  icon on the SIS Pre-Registration page, is solely used to change the language for the dynamic form content on the page. It does not impact the translation of system-defined content.

• To ensure that parent locales are stored correctly, and emails are sent in their respective languages, administrators must re-save any existing Pre-Registration forms on the administrator portal.

In the default property file, there can be different types of messages.

Message Types in Property Files

The message text will sometimes contain literal strings that can be translated as is. For example:

eec.js.scripts_formbuilder_js.main.noresponsestoform=There are no previous responses to this form

The message text is the text that follows the message key. In this example, the message text can be translated to French as follows:

eec.js.scripts_formbuilder_js.main.noresponsestoform=Il n'y a pas de réponses précédentes à ce formulaire

Text with HTML Fragments

The message text will sometimes contain HTML tags which should be retained within the translated text to maintain the display formatting of the text in the other language. For example:

eec.js.scripts_formbuilder_js.main.swal_contact_associatedataaccesswarningmessag=Contact can not been removed if associate with Data Access. <br /> However, you can edit the details of contact information.

In this example, <br /> is an HTML fragment which causes the content to be display on two lines:

When translated, this HTML tag should be retained between the two sentences: 

eec.js.scripts_formbuilder_js.main.swal_contact_associatedataaccesswarningmessag=Le contact ne peut pas être supprimé s'il est associé à l'accès aux données. <br /> Cependant, vous pouvez modifier les détails des informations de contact.

Text with Parameterized Indexes

The message text will sometimes contain numbers (indexes) within curly brackets like {0} which should be retained within the translated text to maintain the integrity of the content in the other language. These indexes will be replaced with dynamic values from the application. These values are not static text and need to be inserted when rendering in the application. For example:

eec.js.scripts_formbuilder_js.main.swal_contact_deletedcontacttext=<strong>{0} {1}</strong> has been removed. <br />This change will be saved when you submit the form.

In this example, {0} and {1} are the indexes which will be replaced with dynamic values of the contact's first and last name, respectively, that was just deleted.

When translated, these indexes should be retained in the appropriate location: 

eec.js.scripts_formbuilder_js.main.swal_contact_deletedcontacttext=<strong>{0} {1}</strong> a été supprimé. <br />Cette modification sera enregistrée lorsque vous soumettrez le formulaire.

Rename the Property Files

Rename your copy of each property file based on your language using the following format:  

• eec_admin_template.{locale}.properties

• eec_parent_template.{locale}.properties

• eec_pre-registration_template.{locale}.properties  

• eec_teacher_template.{locale}.properties

Refer to the country_language locale info.xlsx file to identify the country and language codes needed to build your locale.

• {locale} is based on your translation locale  

• locale = country code_language code

The Excel sheet contains all the acceptable country and language codes. Some examples are as follows.

Build the Plugin with Translated Property Files

Replace the template property files with your translated property files.

1. Save all the changes made in the property files.

2. Replace the template property files with your files in the MessageKeys folder.

3. The plugin.xml file needs to remain as is, no changes are required.

4. Compress this folder by selecting the MessageKeys folder and the plugin.xml file.

5. Rename the zipped file as Ecollect-TranslationManager.

You will now have a zipped file which is your plugin with translations added.

Install and Enable the Ecollect-TranslationManager Plugin

1. Log in to your PowerSchool SIS - admin portal.  

2. Navigate to the Plugin Management dashboard:

   • Enhanced UI navigation: Start Page, System Management, Server, and Plugin Configuration.

   • Old UI navigation: Start Page, System Administrator, System Settings, and Plugin Management Dashboard.

3. Click Install and then select Choose File.

4. Select the compressed file you created, click Open and Install.

5. On the plugin management dashboard, find the plugin you just added, select the checkbox next to it, and click Enable.

6. Once enabled, the UI will be translated based on the user’s login language.

It is important to maintain a local copy of your plugin with translated property files in an accessible location.

Test the Translation

Perform the prerequisite setup as described.

Upgrade the Ecollect-TranslationManager Plugin

For each release, new message keys may be added to the property files or existing message keys can be updated. This will require you to update your Ecollect-TranslationManager plugin with the updated translations.

1. Download the Ecollect-TranslationManager plugin.

2. Extract the content to view the property files. Review the Message Types for detailed instructions on interpreting the message keys within the property files.

3. Identify the recently added or updated message keys and copy them from the template property files. These message keys are always provided as comments at the beginning of the files for easier identification. Search for these keys in the property file and add translations accordingly.

4. Navigate to your local copy of the plugin that contained the previously translated property files.

   1. Add new message keys and/or updated message keys to the respective files.

   2. Save all the changes made in the property files in your copy of the plugin.

5. Delete the plugin.xml file in your local copy of the plugin and replace it with the new plugin.xml file located in the Ecollect-TranslationManager plugin.

6. Delete the previously installed Ecollect-TranslationManager plugin from your PowerSchool SIS instance.

   1. Log in to your https://<sisurl>/admin/pw.html portal.  

   2. Navigate to the https://<sisurl>/admin/pluginconsole/plugInConsole.action dashboard:

      • Enhanced UI navigation: Start Page, System Management, Server, and Plugin Configuration.

      • Old UI navigation: Start Page, System Administrator, System Settings, and Plugin Management Dashboard.

   3. Find the Ecollect-TranslationManager plugin and click Delete.

7. Install and enable the Ecollect-TranslationManager plugin with the updated property files on your PowerSchool SIS instance.

   1. Log in to your https://<sisurl>/admin/pw.html portal.  

   2. Navigate to the https://<sisurl>/admin/pluginconsole/plugInConsole.action dashboard:

      • Enhanced UI navigation: Start Page, System Management, Server, and Plugin Configuration.

      • Old UI navigation: Start Page, System Administrator, System Settings, and Plugin Management Dashboard.

   3. Click Install and then select Choose File.

   4. Select the compressed file you created, click Open and Install.

   5. On the plugin management dashboard, find the plugin you just added, select the checkbox next to it, and click Enable.

You now have updated translations on your product.

Trouble Shooting Guide

If you upgrade your Ecollect Forms/Enrollment Express version but do not update the Ecollect-TranslationManager plugin with translations for new message keys, the UI will show English text by default.

• What happens if the plugin is built incorrectly?
  Errors when building the plugin, such as omitting the plugin.xml or not compressing the file, will result in the following error:
  No plugin definition file ‘plugin.xml’ found in archive.

• What happens if there are mistakes in naming the property file or file extension?
  The naming of the properties files is important. If they do not use the correct locale name and file extension .properties, then the translated messages will not appear on the UI.

• What happens if they have the English template file and their translated files?
  Avoid including the English template file in the Ecollect-TranslationManager plugin.