Difference between revisions of "Resources/Translation"

Latest revision as of 14:22, 7 October 2022

Main Page > Resources > Resources/Translation

Thank you for your interest in contributing user interface translations to the AtoM project! Your contributions help to further AtoM as a multilingual application with a global reach.

In our continuing efforts to make the process of translating the AtoM interface more efficient, Artefactual Systems has moved from its previous translation service, Transifex to Weblate, an open source web-based translation management system supporting continuous translation from multiple sources. More than one translator can contribute translated strings, making the process fast and easy, and enabling Artefactual Systems to publish translations more often. Everything is web-based using Weblate, meaning you can access your translation work via any web browser.

This page will introduce you to the AtoM Weblate translation project, so that you can log in and begin translating. If you have contributed through Transifex in the past, you will notice that the log in process with Weblate is slightly different, but contributing translations continues to be easy and flexible.

Log in to contribute to Artefactual translations

The AtoM project in Weblate lives here:

• https://translations.artefactual.com/

When first arriving, you will be asked to log in or create a new account. If you already have an account, you can either enter your login credentials (if you created a local account via Weblate), or use one of the social authentication options to complete the sign-in, if you registered using a GitHub or Google Account.

Creating a new translator's account in Weblate

1. From the homepage, you will see two options to register. Click on one of the links:

Artefactual has configured social authentication options, using either a GitHub or a Google account. We recommend using these over creating a local Weblate account whenever possible. If you already have accounts on these services you can use them to authenticate by clicking the related login option on the landing page.

Both GitHub and Google offer free account creation. You can find sign-up buttons on the homepage for each service:

• GitHub: https://github.com
• Google: https://www.google.com/account/about/

Depending on the service you use, there may be a few additional steps. See the GitHub sign-up example below for more information.

After authenticating for the first time, you will be taken to the Terms of Service page. Check the "I agree" checkbox below the terms, and then click the Submit button.

Once signed, in, if you used one of the social authentication options you may be prompted to configure a local password, despite signing in with a Google or GitHub account.

This password will be used to confirm local Weblate account settings changes. You will still be able to use your social (e.g. GitHub or Google) account for authentication in the future, but certain key changes in your account settings in Weblate will prompt you to provide the password you configure in the following steps.

On the following screen, enter and then confirm a new password for local account settings modifications:

Once approved, you will be redirected to the Weblate dashboard. At first, this may be empty:

However, once you've configured your preferences, this will act as your initial landing page, showing all the available components for translation in your Watched projects and preferred translation languages.

Social Authentication example: signing up with GitHub

Below is an example of some of the additional first steps you'll encounter when first registering with a GitHub account. The process will be similar, though some steps may be slightly different, if using a Google account instead.

From the registration page, click on the GitHub button. You'll be taken to a sign-in page - enter your GitHub account credentials:

The first time you log in you will be asked to grant access to your GitHub account. Click the button labeled, "Authorize translations.artefactual.com by qubot" to proceed.

This is a one-time authorization step - you will not see this screen on subsequent logins.

From here, the process will be the same - see the steps above for agreeing to the Terms of Service, setting up a local password, and arriving at the Dashboard.

Set your preferences

2. When you sign in you will see the Dashboard and menu options. Once configured, the Weblate Dashboard provides an overview of projects and components, as well as their respective translation progression. Components of projects you are watching are shown by default, and cross-referenced with your preferred languages.

For new accounts, this Dashboard may be empty at first, so let's configure it. You can set or change your preferences a number of ways from the Dashboard.

Under your profile, click the "Settings" option.

This will take you to a page where you can configure the default language of the Weblate interface, as well as your languages for translation.

Choose the languages you wish to translate and those you may want to follow. Choose your primary languages from the Translated languages box. These are the languages you speak fluently and wish to translate. They will show up on your dashboard as "Watched languages" when you log in or navigate to the Dashboard. If there are other languages you want to follow, choose those in the Secondary languages box. Strings that have been translated in these languages will appear on the translation page (see #Begin translating). When you have made your selections, click "Save". You can change these settings at any time by returning to the Languages tab in settings.

You can update this at any time, either by following the same steps above, or by opening the Languages menu and clicking the "Manage translated languages" option.

Under the Projects menu in the header, you can click the "Manage watched projects" to configure what translation projects in Weblate you wish to follow. Currently Artefactual has only one translation project - atom. Even though there is currently only one project, choose it and click "Save" so that it will appear in your dashboard.

There are other notification settings on this page, which can also be accessed by opening the menu under your user profile, clicking the "Settings" option, and then clicking the "Notifications" tab. Translation notifications apply to your primary languages. This can be especially useful for users who are designated reviewers (see #Become a reviewer). When you are done, save your selections.

From the Preferences tab you can choose how you would like the translation screen to appear. Translation editor mode offers two choices - Full editor mode and Zen mode. These are described below in Begin translating.

Be sure to review some of the other customization options available via the different tabs on the Settings page as well, such as the "Account" and "Profile" tabs.

3. Once you have configured your preferences, these will appear on your Dashboard, showing the status of translation for each of your chosen languages and projects. You will also see a Projects dropdown list on the main navigation bar at the top of the page; all Artefactual translation projects are available from the Projects dropdown list, and all available languages from the Languages dropdown list.

In the screenshot below, the user has selected two primary languages - these will always be shown on the dashboard for the available components of watched projects when that user logs in.

Components in Weblate

4. In Weblate translations are organized into projects and components. Each project can contain number of components and those contain translations into individual languages. The components typically correspond to one translatable file.

For AtoM, we typically add new translations in major release versions (e.g. 2.7, 2.8, etc). Correspondingly, there will be a component for the major version currently open for translation in advance of the next public release. Additionally the AtoM website has some translatable strings - these can be found under the "website" component.

To browse available components, use the "Projects" menu in the header, and select AtoM. By default this will show the Components tab. You can click on a component to see the available languages for translation in that component, including those you have not added to your Dashboard via the preferences. From the the list of languages, clicking on any will open the translation interface, so you can begin translating in your selected language.

Requesting new languages

5. Don't see a language you would like to provide translations for? If you would like to translate in a language that is not currently available in our Weblate project, you can request that it be added.

To start a request, click on the project component in which you plan to add translations (e.g. 2.7). From the Tools menus select "Start new translation" or scroll to the bottom of the list of languages and click on "Start new translation" at the bottom of the page.

From the tools menu:

From the bottom of the page:

Weblate will redirect you to a new translation configuration page. Select the language(s) you would like added to the project from the list on the left under the "Available" heading - it should then appear in the right-hand column under the "Chosen" heading. When you've made your selection, click the Request new translation button at the bottom of the form.

If the languages listed still do not include one that you want to translate, click the link "Can't find your language in the list above?".

Complete the Weblate form with as much detail as possible using information from this list and click Send. Your request will be received by Artefactual.

Once your request has been submitted, Artefactual staff will receive a notification, and our project team members will add the requested language as soon as possible. If you have further questions, feel free to contact us at translate@artefactual.com.

Begin translating

6. From your dashboard you can navigate directly to the translation screen by clicking on the pencil icon next to any of your selected translation languages.

Alternatively, you can see an overview of the translation process for a particular language by clicking on the language name in the components list. This will take you to the Overview screen of the main translation page for that language.

Clicking on the "Translate" button will take you to the set of strings needing action. You can also choose different filtered sets by clicking any of the links under Strings to check on the overview page.

Tip

Any of these filtered options available in the Overview page can also be reached directly from the translation interface, using the filter options available in the header:

7. Once you have reached the translation screen you will see the first item needing translation. The default view is Full editor mode; the screen shows any relevant contextual information in the right-hand column, the source string to be translated, and a text field in which you can enter your translation.

You can enter your translation and press the "Save and continue" button to load the next string for translation. If you are unsure how to translate a particular string, you can skip it with the "Skip" button. Alternatively, a "suggestion" works like a comment - other translators will be able to see suggested translations saved using the "Suggest" button, but nothing will be added to AtoM until a translator decides to submit and save a translation string.

Below, additional contextual information is provided that might help with string translation. The "Nearby strings" tab will show other source strings from the same translation file, that might help provide context. The "Comments" tab can be used to see comments by previous translators and reviewers, or to leave a comment of your own - this can be useful if you are uncertain how to translate a string and would like input, or to discuss a translation choice with a Reviewer.

The "Automatic suggestions" tab searches for similar strings and translations from the project history and the AtoM Weblate translation memory (including from older Components, when translations may not have been carried forward for some reason), and even other Weblate projects:

When relevant these can be copied and then modified as needed, or even copied directly and saved as a new translation in the current Component.

Important

Variables and HTML

Many source strings include variables, e.g. %1%, or (%3% b). These should be included in the translated string in the appropriate position for the destination language:

For example, in the image shown above,

%1%Download%2% (%3% b)

should be translated into Spanish as:

%1%Descarga%2% (%3% b)

Follow the same approach when encountering HTML elements in a source string.

8. When you have entered your translation, click one of the Save buttons. Your translation will be saved and checked by Weblate's quality checks. If there are any failing checks a message will appear. You can then edit your translation and resave, or leave the translation as is and move on to the next source string. You can skip any strings you do not want to translate.

Tip

All translations are saved in Weblate regardless of failing checks. Weblate runs a wide range of quality checks on each translation, including syntax, length, consistency, duplication and more, taking into account special rules for different languages. See types of translation checks here. Any translation that has not been approved by a designated reviewer can be edited by any logged in user, including fixing failed checks or editing a saved translation.

You can review all strings where Weblate (or another user) has flagged an issue, using the filters available at the top of the translation page (e.g. selecting the "Strings with any failing checks" option). Any issues found by Weblate's automatic checks will be shown in the right-hand context menu.

A translator or reviewer can also set the State of the translation, marking it as "Needs editing," or "Waiting for review." On a Reviewer can set the string as "Approved." For more information on Reviewers, see the section on Review below.

Finally, you can also use the tabs below the translation interface to leave a comment or review previous comments, look at translation suggestions that might help improve the translation, and more.

9. For a faster translation workflow with a less cluttered interface, switch to Zen mode by clicking Zen at the top right of the screen. In Zen mode each item shows (1) the source string location (i.e. the location of the source string in the Artefactual code repository), (2) the string to be translated, (3) a place for you to add your translation in the current watched language, and (4) depending on your user permissions, any options you have for setting the Review state.

You can switch from Zen mode back to Full Editor mode by clicking Exit Zen.

In Zen mode your translation will be saved automatically, and checked, once you move your cursor out of the translation field. If your translation fails any checks, a red banner notification will appear, describing the issues found.

You can work through the list of strings needing translation, choosing those you want to translate.

10. You can contribute translations in any language, even those you have not set as primary or secondary in your preferences. Clicking on a project component will bring up a list of all languages in the project. Click the pencil icon next to any language to go to the translation screen for that language. To arrive at the list of all languages currently available for a component, use the main menu: under the Projects menu in the main header, click atom (if you've added it as a watched project in your preferences - otherwise you can browse projects to find the AtoM project), and then select the component you want. AtoM will then display a list of all available languages for that component - you can sort by the various columns shown:

11. Your translations are all saved in Weblate. However, before they can be included into the public branch of AtoM they need to be approved by designated reviewers, and then pushed to AtoM by Artefactual administrators.

Become a reviewer

12. Before translations from Weblate are added to AtoM they must be approved by designated reviewers. Reviewers are community members who are willing the review and approve translations in languages in which they are proficient. Once a translation is approved it cannot be changed (except by an administrator). These approved and locked translations are then ready to be incorporated into the main AtoM site. This will be done periodically by Artefactual, typically before major releases.

13. All logged-in users at https://translations.artefactual.com have translator privileges that allow them to enter translations and edit their own and others' translations prior to approval. Reviewers have the same privileges as translators, as well as privileges that allow them to approve (and therefore lock) translations. If you would like to be a reviewer, log into the translation project. This will ensure that your email is registered with the site as a translator, and visible to the Artefactual administrators. Then send us an email at translate@artefactual.com so that we can grant you reviewer privileges.

14. Once you have reviewer privileges you can search for strings to be approved in your primary language(s). Click on Strings waiting for review from the translation overview screen in your chosen language. In Full editor mode this link appears in the list of String statuses:

You can also filter to show those strings waiting for review from the Translation edit page, using drop down filter at the top of the page. This option will work from both the full editor as well a Zen mode (shown below):

For each string needing approval, you can click the radio button Approved to lock the translation for that string. Remember to click Save if you are using Full editor mode.

15. Several times through the year Artefactual developers will push approved strings into the main AtoM branch, typically a while before we plan on releasing the next version. We'll make announcements in both the AtoM user forum and via Weblate's announcements several weeks before these events to request that Translators finish any in-progress translations, and that Reviewers approve new translations in their designated languages

Reviewing Translations

16. We would ask reviewers when they are verifying translations to please ensure that the notations that appear in the original English, also appear in the translations.

If they do not appear in the translated string, we would ask reviewers to add them in before approving the translation.

17. There is a warning that might appear with some translations about starting spaces, blank spaces or other formatting issues; these will need to be addressed. The first step to resolve these issues will be to select ‘Fix String’ and then select ‘Save and stay’. Please do not dismiss this error, it must be correct for the translation to be accepted.

Once the issue has been resolved then reviewers can proceed to finalizing and approving the translation.

18. Weblate may throw up a warning saying that the translation provided in ‘Inconsistent’ See example below:

Weblate compares strings across the whole AtoM project, this error does not in principle mean there is an issue with this translation, but a reviewer may wish to browse through the language repository where they are working to see if there are any issues with the consistency of the translation provided. Translation is, of course, context dependent and so the issues identified by Weblate may not in fact be a problem with the translation being reviewed. If there are no issues then reviewers can dismiss this error and select ‘Save and Stay’ to continue reviewing the translation they are working on.

FAQs

Below you'll find some responses to frequently asked questions about Weblate, and our move from Transifex. You can also explore the Weblate documentation - here are a few handy links:

• Weblate basics
• Translating using Weblate
• Weblate: Frequently Asked Questions

I just got comfortable using Transifex - Why are you moving from Transifex to Weblate?

Artefactual was previously able to use Transifex because they offered free plans to open source projects. As of 2018, Transifex changed its policy to limit these free accounts to small projects with 10 collaborators or less - and because AtoM has a vibrant translation community with dozens of translators, we no longer qualify. A paid plan with Transifex that could support as many collaborators as we need would cost at least $1,500 USD a month to maintain, which would represent a serious drain on the resources we have to maintain the project. Instead, we have chosen to move to an open source platform, Weblate, so we can host and manage the application ourselves.

Weblate has changed a lot since I last used it! Why?

When we first moved from Transifex to Weblate, Artefactual installed and maintained a local version of Weblate version 3.2. However, our small team ran into some issues maintaining this local version, eventually leading us to lock the translation platform until we could resolve these issues. In the meantime, the Weblate project continued developing, including releasing a 4.x version that introduced a major overhaul to the user interface, and other workflow changes.

In April of 2022, our team decided to move our translations platform to a hosted Weblate instance. This freed up Artefactual staff time so we can better focus on Artefactual projects and clients, and allows us to draw on the expertise of the Weblate development team in supporting our translation platform. It also means that Artefactual can support another organization with a similar open-source business model to us - something we are always happy to be able to do!

The Weblate hosting team helped to migrate our content, add Google account authentication, and upgrade Weblate to the latest version. The many changes you see are a result of this upgrade from version 3.x to version 4.x.

Why do you prefer I log in through GitHub or Google?

Now that Artefactual is hosting and maintaining our translation infrastructure, we expect that many bots, web crawlers, and spam accounts would hit our user registration page, requiring significant time and energy to manage. GitHub and Google are long-established platforms with existing filters and checks in place to reduce these kinds of spurious registration attempts, so we don't have to do it manually.

Artefactual already makes use of GitHub for AtoM's code repository and documentation, and going forward, the translation strings for each release will also be maintained in a separate GitHub repository.

With our shift to a hosted Weblate instance, we've now added Google authentication support as well, which may be more useful for archivists without a GitHub account.

Both GitHub and Google offer free accounts.

There are two components in the Weblate AtoM project - which one should I use?

Generally, Artefactual offers two kinds of releases: a major release (e.g. 2.7, 2.8, 2.9 etc) and sometimes, a minor release (e.g. 2.7.1, 2.7.2, 2.8.1, etc). Major releases include new features and enhancements, while in most cases, minor releases will only include bug fixes. Both releases may include translation updates if they have been provided by our community. In Weblate, components will only have major numbers (e.g. 2.4, 2.5, 2.6, etc) and will be used to prepare any releases, major or minor, relating to the component number.

In most cases, there should only be one unlocked component in Weblate's AtoM project - if we've released 2.7 for example but expect to create a 2.7.1 release, we will likely not open a 2.8 component until 2.7.1 has been released, so that translators don't have add the same translations to both components.

However, there may be rare cases where we have two components open and unlocked. This might occur if, for example, we've already added a 2.8 component, but then discover an issue in 2.7 big enough to warrant a 2.7.1 release, and want to allow our translator community an opportunity to supplement or update existing translations in that release as well.

In this rare case, it's up to you which component you choose to work in - but it should be informed by your goals, and a clear understanding of the consequences.

In the example above, translations added to 2.7 will not automatically appear in the 2.8 component, and vice versa. For this reason, whenever possible Artefactual will avoid keeping multiple components open at once.

Because of this, when encountering multiple open components for AtoM in Weblate, we recommend only working in the earlier component if you want to fix poor translations or make other minor improvements in the next minor release so you can access them more quickly (since this will be the next public release), and you don't mind losing them in the next release or manually making the same changes in the later component. Otherwise, we recommend focusing on the latest component available - this ensures that your translations will be included in future releases as well.

What's the difference between a reviewer and translator?

Every person who logs into our AtoM translation project will automatically be a translator. That means you can choose projects, and primary and secondary languages to watch, add translations in your chosen language(s) and any other languages you have knowledge of, and request that new languages that are currently unavailable in the project be added to it. When you add a translation, that string is automatically saved in the Weblate database and becomes visible to everyone. It can still be edited by you or by other translators. However, it will not be part of the next Artefactual commit until it has been approved. That is the role of a reviewer.

Reviewers have all the same privileges as translators, as well as the ability to approve translations. Once a reviewer has approved a translation it will no longer be editable, and it will be part of the next Artefactual commit.

Why do I need a reviewer?

Artefactual has chosen to use this model in order to maintain quality control on translations. If you would like to be a reviewer, please let us know by sending an email to translate@artefactual.com.

What do I do if there are no reviewers on my language?

We try to track who is a reviewer for any given language, and will contact translators directly if reviewers are needed for a language. If you find yourself completing translations with no reviewer for your chosen language(s), please feel free to contact us at translate@artefactual.com.

In such a case, we can discuss options - generally, either we will propose making you a reviewer, or automatically approving your translations before a release (so they can be included in the upcoming release) until a suitable reviewer can be found.

Why can't I translate in a specific sublocale (like ES_es)?

AtoM was built using the Symfony 1.x PHP framework, and we borrow its internationalization (or i18n) functionality to implement AtoM's ability to translate content into multiple languages. However, as an older framework, Symfony's support for specific sublocales is limited. AtoM cannot at this time support a language that is not supported by the underlying Symfony i18n framework.

Where can I find a list of supported languages for translation in AtoM?

We have a list of all of AtoM's supported languages, and their 2-letter ISO 639-1 language codes, here:

• http://bit.ly/AtoM-langs

How do I request a new language?

First, please make sure that the language you would like to request is supported in AtoM - see this list:

• http://bit.ly/AtoM-langs

If it is supported, but you don't see it in Weblate, please see the "Requesting new languages" section above. You can request a new language via Weblate - here's a quick summary of the steps outlined above:

• Navigate to the AtoM component in which you want to work
• Click the "Start new translation" button at the bottom of the page
• In the Language selection page that will appear, click the "Can't find your language in the list above?" hyperlink
• Weblate will open a Contact form - please fill out the details of your request. Artefactual will receive it and review the request. If you've requested a language that AtoM supports (full list available here), we'll approve it!

See the documentation section above for more details and screenshots.

Alternatively, feel free to email us at translate@artefactual.com and we will be happy to add a new language for you!

Thank you for helping us translate AtoM - it is through your participation that we can make AtoM a truly international application!

Got questions, or find something that's not covered below that you think would be helpful? Let us know via the AtoM User Forum, or send us an email at translate@artefactual.com.

• Back to Resources
• AtoM wiki home