Choosing a Language for the User Interface

As of version 2.6.5 Quoll Writer allows for different languages to be used for the User Interface. Note: this page assumes that you are using the English language when interacting with Quoll Writer.

A translation can be selected by going to the How things look & sound section of the Options panel and selecting a language from the drop down list. Quoll Writer will then download the selected translation, it is recommended that you then restart Quoll Writer to make full use of the translation.

Creating a User Interface Translation

Note: the Language Strings Editor is a beta feature that is new and probably not feature complete. I've never created a translation for a User Interface before so I'm breaking new ground. I need to hear from you about features you'd like to see or think you need for creating a set of strings for a translation.

Please note the creation of a User Interface translation for other Quoll Writer users is subject to the following terms and conditions.

You can create your own User Interface translation by clicking the Create a translation button under the language select drop down list.

After entering the native name for the strings, i.e. the name the language speaker would recognise, the Language Strings Editor will be shown.

The Language Strings Editor

This window, as shown below, allows you to enter your own value for each of the strings used in the User Interface. Strings are broken into logical sections, for instance labels used on buttons can be found in the Button Labels section, strings relating to full screen mode can be found under the Project / Full Screen Mode section. Each string has an associated id. Quoll Writer uses ids to find the right string to display to the user in the interface.

The Editor uses a similar structure to a normal Quoll Writer Project, as explained below.

• On the left is the sidebar where you can access the various sections of strings.
• The panel on the right shows the strings associated with the currently selected section. In the image the strings for Actions are displayed.
• At the top right are a number of buttons that will be explained later.
• Each section has a comment associated with it giving an indication of the purpose of the strings.
• Each string has an English value, this is the default value. You can enter your own value in the Your Value box.

A single string

Let's look at a single string in detail.

There is a lot going on in this example, so let's break it down.

• First, we are editing strings in the Deleting Items section, the comment describes the area where these strings are used.
• Under the section comment we see the strings id. This will become relevant later, but the important thing to note is that every string used in the User Interface has its own unique id.
• This string has its own comment. In this case it describes a value that must be present somewhere in the string, more on that later.
• Under the string comment is the English value. If you don't provide a value for the string then the English value will be used instead.
• The box next to Your Value allows you to enter your own translated version of the English string. In this case we have used You must delete this but from the comment it shows that the value %1$s must be present somewhere in the string.
• Finally because the required value isn't present an error is shown indicating what is wrong.

Below is an image of what happens when the value is amended to include the required value.

Notice that the error has disappeared and in its place a Preview is displayed.

Required values

There are many strings used throughout the User Interface that require dynamic values to be displayed. These dynamic values are replaced in the strings and then displayed to the user. To perform the replacements Quoll Writer needs to use special values that it can find within the string and then replace that value with the dynamic value.

Quoll Writer uses the form %X$s to represent the values to be replaced, where X is an integer, starting at 1 and increasing by one for each subsequent dynamic value. For example, in the string This %1$s is a %2$s, value %1$s could be replaced with cake and value %2$s with lie to create the final string This cake is a lie.

Each %X$s value can be used multiple times in the string, the comment associated with the string will tell you what %X$s values are required and what each of them will be replaced with.

Some examples:

• String: Create a new %1$s, replace value %1$s with Project, so the final string becomes: Create a new Project.
• String: My %1$s was copied from another %1$s, replace value %1$s with Project, so the final string becomes: My Project was copied from another Project.
• String: My %1$s was copied from another %1$s to create my new %2$s, replace value %1$s with Project, replace value %2$s with Book so the final string becomes: My Project was copied from another Project to create my new Book.

Reusable Values

The English strings make heavy use of reusable values. This is a special piece of text that refers to another string by its id. To include a reusable value in your string use the value ${id}. A common example used throughout the English strings is the name of objects such as that for a Project. To reference the name for a Project use ${objectnames.singular.project}. Similarly you can reference the name for multiple (plural) Projects by using ${objectnames.plural.project}. When Quoll Writer sees the form ${id} it will look up the current value for that id and replace the value in the string. An example is shown below, notice the preview value.

Reusable values allow you to reuse previously defined values and prevent spelling mistakes and maintain consistency in the interface.

If the id used in a ${id} value is wrong, i.e. Quoll Writer cannot find that string, then an error will be displayed as shown below.

To help prevent this type of error the Editor will display a red line under the id, i.e. it detects that it is spelled incorrectly. Also if you type ${ the Editor will display a popup select list of the available strings that match the current value, some examples are shown below.

Selecting about. Matches for ids with that prefix are then displayed.

popup is selected, again the matching ids for the prefix are then displayed.

You can use the arrow keys to navigate through the list and then either press return or tab to accept the selected value.

Some examples:

• String: Create a new ${objectnames.singular.project}, becomes: Create a new Project.
• String: ${objectnames.singular.chapter}: %1$s in ${objectnames.singular.project}: %2$s needs saving, replace %1$s with It Begins, replace %2$s with My First Project, the string becomes: Chapter: It Begins! in Project: My First Project needs saving

Testing your strings

The try out icon on the right hand side of the header bar allows you to test your strings within the Quoll Writer interface. You should then restart Quoll Writer to ensure that the interface is updated to reflect your strings. The User Interface language select drop down in the Options panel will be updated to show that your strings are being used. Strings created by you have a suffix of (Created by you) in the drop down.

Editing your strings

To edit a set of strings you have previously created use the Edit one of your translations button in the How things look & sound section of the Options panel and select the strings to edit.

Submitting your strings

To submit your strings for use by other users of Quoll Writer use the submit button on the header (the up arrow button). The following popup will be displayed.

You'll need to provide the English name for your strings and a valid email address where you can be contacted about your translation. This is used for feedback about your translation from users and for notifications about upcoming changes that may affect your translation. Upon submission of the strings a confirmation email is sent to the email address, you must click the link in that email to complete the submission and confirm your email address. Note: if the email address becomes invalid then your translation may be removed or given over to another Quoll Writer user for maintenance purposes. Once the submission process is complete the translation will be available to Quoll Writer users who will be able to send you feedback but will not have your email address revealed to them.

Keeping your strings up to date

When a new version of the English strings is available you will receive an email to the email address provided when you first submitted the strings to the Quoll Writer server. The Language Strings Editor will check, when you edit a set of your strings to see if a new version of the English strings are available and if so offer to display the differences between the current Quoll Writer version you are using and the new version.

An example is shown below:

This allows you to focus on the new/changed strings only. You can submit a new version of your strings at any time. The link in the top left hand corner lets you switch between just the changed/new strings and all strings.

Deleting your strings

You can delete your strings at any time. If you have previously submitted the strings for release to Quoll Writer users then your strings will be deleted from the Quoll Writer server but still be available for use by users if they have previously downloaded the strings, i.e. existing users can still use the strings, but no new users will be able to download them.

Additionally, you can choose to delete all versions of your strings by clicking the box as shown in the example below.

Terms & Conditions

The Terms & Conditions for creating a set of strings for a translation can be found here.