Difference between revisions of "Resources/Translation"

From AtoM wiki
(Join the AtoM Project)
(Become a reviewer)
 
(38 intermediate revisions by 4 users not shown)
Line 2: Line 2:
 
[[Main Page]] > [[Resources]] > Resources/Translation
 
[[Main Page]] > [[Resources]] > Resources/Translation
  
Thank you for your interest in contributing user interface translations to the AtoM project! Your contributions help to make AtoM a multilingual application with a global reach.
+
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 an effort to make the process of translating the AtoM interface more efficient, Artefactual Systems has started using [https://www.transifex.com/ Transifex], a web application to support dynamic publication of localization content from multiple sources. This means that more than one translator can contribute translated strings, making the process faster and easier, and enabling Artefactual Systems to publish translations more often. As well, everything is web-based using Transifex, meaning you can access your translation work via any web browser, instead of having to handle [https://en.wikipedia.org/wiki/XLIFF XLIFF] files directly, as was the case with early versions of ICA-AtoM translations.
+
In our continuing efforts to make the process of translating the AtoM interface more efficient, Artefactual Systems has moved from its previous translation service, [https://www.transifex.com/ Transifex] to [https://www.weblate.org/ 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 Transifex project, so that you can sign up and begin contributing translations. When we package the next public release, we will include all translations submitted via Transifex in the release - so the entire community will benefit from your contributions.
+
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.
  
 
<admonition type="seealso">
 
<admonition type="seealso">
* Interested in contributing to our project documentation? We have a separate page for that! See: [[Resources/Documentation/Contribute|Contribute documentation]]
+
* Interested in contributing to our project documentation? We have a separate page for that! See:[[Resources/Documentation/Contribute|Contribute documentation]]
 
* Looking to contribute code to AtoM? See: [[Development/Contribute code|Contribute code]]
 
* Looking to contribute code to AtoM? See: [[Development/Contribute code|Contribute code]]
 
* Check out our [https://www.accesstomemory.org/docs User Manual] for information on how to translate content or interface elements locally (in your installation only) - see the Multilingual section.
 
* Check out our [https://www.accesstomemory.org/docs User Manual] for information on how to translate content or interface elements locally (in your installation only) - see the Multilingual section.
 +
* Got questions, or find something that's not covered below that you think would be helpful? Let us know via the AtoM [https://groups.google.com/g/ica-atom-users User Forum], or send us an email at [mailto:translate@artefactual.com translate@artefactual.com].
 
</admonition>
 
</admonition>
  
'''You can see the AtoM project in Transifex here:''' https://www.transifex.com/projects/p/atom/
 
  
 +
__TOC__
 +
 +
 +
==Log in to contribute to Artefactual translations==
 +
 +
'''The AtoM project in Weblate lives here:'''
 +
 +
* https://translations.artefactual.com/
 +
 +
<br />
 +
 +
[[File:weblate-first-view.png|frameless|600px|center|Login page]]
 +
 +
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:
 +
 +
[[File:weblate-login.png|frameless|600px|center|Login page]]
 +
 +
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:
  
__TOC__
+
* GitHub: [https://github.com https://github.com]
 +
* Google: [https://www.google.com/account/about/ https://www.google.com/account/about/]
  
 +
Depending on the service you use, there may be a few additional steps. See the [[#Social_Authentication_example:_signing_up_with_GitHub|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.
  
===Sign up for an account with Transifex===
+
[[File:weblate-tos.png|frameless|600px|center|Weblate's terms of service]]
  
'''1.''' Navigate to https://www.transifex.com/signup/
+
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.
  
[[File:transifex-signup.png|thumb|400px|center|Sign-up page for Transifex]]
+
[[File:weblate-local-auth.png|frameless|600px|center|Configuring a local password in Weblate]]
  
 +
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.
  
'''2.''' Fill in all the required fields, click on “Create my Account” (note: by doing so you are agreeing with the Transifex Terms of Use). If you have an existing Google,  GitHub, or LinkedIn account, you can use this to create your Transifex account.
+
On the following screen, enter and then confirm a new password for local account settings modifications:
  
<admonition type="seealso">
+
[[File:weblate-local-pass.png|frameless|600px|center|Configuring a local password in Weblate]]
Transifex has its own help documentation - here's a help page on getting started:
 
* [http://docs.transifex.com/introduction/translators/ Getting Started as a Translator]
 
</admonition>
 
  
===Join the AtoM Project===
+
Once approved, you will be redirected to the Weblate dashboard. At first, this may be empty:
  
'''3.''' Once you have created an account, you will be redirected to a configuration page. Fill in your name and preferences.
+
[[File:weblate-dash-empty.png|frameless|600px|center|An empty dashboard after creating a new account]]
  
'''4.''' On the second configuration page, you will be given the option to start your own project or to join an existing one. Select "Join an existing project".
+
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.
  
[[File:transifex-find-projects.png|thumb|400px|center|Configuration page for Transifex. Click the "Find projects" button after inputting your preferences and languages]]
+
====Social Authentication example: signing up with GitHub====
  
'''5.''' The last configuration page will ask you to identify languages that you speak. Select as many as are applicable and click on "Get started".
+
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.
  
'''6.''' A pop-up window will appear. After you click on "Find a project to translate", type "atom" into the search bar and then click on the AtoM project when it appears below.
+
From the registration page, click on the GitHub button. You'll be taken to a sign-in page - enter your GitHub account credentials:
  
[[File:transifex-find-atom.png|thumb|400px|center|Project finder for Transifex. Type "atom" into the search bar and then select the AtoM project]]
+
[[File:weblate-github.png|frameless|300px|center|GitHub auth]]
  
'''7.''' You will be redirected to the [https://www.transifex.com/artefactual/atom/ AtoM Transifex Project homepage].
+
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.
  
[[File:transifex-atom.png|thumb|400px|center|The AtoM project homepage in Transifex]]
+
This is a one-time authorization step - you will not see this screen on subsequent logins.
  
===Join a team===
+
[[File:qubot-authorization.png|frameless|300px|center|Authorization]]
  
'''8.''' From the list of languages, select a language whose team you would like to join by clicking on the language name.
+
<br />
  
'''9.''' Transifex will show you a list of available resources (such as the AtoM website, and different major releases of AtoM). At the top of the page on the right-hand side, click the "Join team" button.
+
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.
  
[[File:transifex-join-team.png|thumb|400px|center|Joining a team in the AtoM Transifex project]]
+
==Set your preferences==
  
'''10.''' A pop-up will appear with a list of the available languages. Select your chosen translation language from the list. When you've found it, click the Submit button (if you wish to translate AtoM into multiple languages, you can repeat this process again later).
+
'''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.
  
<admonition type="important">
+
[[File:first-login.png|frameless|500px|center|Weblate dashboard]]
Please review the options available in the list prior to requesting a new language! In many cases, we have had requests for different locales (for example, requesting "fr_FR" for France French, instead of working in the existing "fr" French project), but AtoM does not always support these very well. If at all possible, please work within the existing projects, or try to select the most generic option, without locale codes. We'll work with you if there are no other options, of course - but if you can avoid using a specific locale, it will make merging and maintaining your translations in AtoM much easier!
 
</admonition>
 
  
[[File:transifex-select-language.png|thumb|400px|center|Selecting a language in the AtoM Transifex project]]
+
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.
  
'''11.''' You will see a confirmation message in green at the top of the page, informing you that your request has been submitted. One of the Artefactual project maintainers will review the request and approve your account.
+
Under your profile, click the "Settings" option.
  
'''12.''' You will receive an automated email from Transifex introducing you to the translation editor interface and providing you with a link to generic help instructions. You may review these instructions if you wish, or follow the specific instructions that the AtoM coordinators have provided below.
+
[[File:weblate-settings-link.png|frameless|500px|center|Weblate settings page]]
  
<admonition type="seealso">
+
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.
Here are the links that Transifex will provide you with in the email, for reference:
 
* [http://docs.transifex.com/tutorials/txeditor/ Translating and reviewing content in the Transifex Editor]
 
* [http://docs.transifex.com/ Transifex Help documentation]
 
</admonition>
 
  
'''13.''' Once your account is approved by the AtoM coordinators, you will receive an email notification from Transifex. It will indicate that you have been accepted to the team of the language of your choice within the AtoM project. Once you've received this email, return to the AtoM Project homepage in Transifex (https://www.transifex.com/artefactual/atom/dashboard/) and select your language from the list of project languages at the bottom of the page.
+
[[File:weblate-language-tab.png|frameless|500px|center|Weblate languages settings page]]
  
'''14.''' Transifex will show you a list of available resources (such as the AtoM website, and different major releases of AtoM) at the top of the page. Closed projects (for past releases or future releases for which we have not yet opened translation) will have a red dot next to them. Click on the version you wish to translate - for example, the most recent AtoM release that is open in Transifex.
+
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.
  
'''15.''' A pop-up will appear with information about the current translated strings in that project for your chosen language. Click the "Translate" button to begin working via the web-based Translation Editor in Transifex.
+
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.
  
[[File:transifex-translate-now.png|thumb|400px|center|Click the "Translate" button in the pop-up to begin]]
+
[[File:weblate-lang-menu.png|frameless|500px|center|Weblate settings page]]
  
 
<admonition type="tip">
 
<admonition type="tip">
Want to work translating multiple languages at once? Repeat steps 8-15 above. When you work with the Translation Editor, you will then be able to switch easily between languages.
+
Don't see a language you would like to provide translations for? We have instructions on how you can request new languages in the section [[#Requesting new languages|below]]!
 
</admonition>
 
</admonition>
  
===Use the Translation Editor===
+
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.
  
You are now in the Editor screen. If you are a translator for more than one language/ team you can switch between the available languages using the "language drop-down menu" in the upper-right side of the screen. If you are only translating for one language, the dropdown will not be active.
+
[[File:weblate-watched-projects.png|frameless|500px|center|Weblate settings page]]
  
 
<admonition type="tip">
 
<admonition type="tip">
Note that you can always get here from the Transifex AtoM project landing page:
+
In the future, Artefactual hopes to use Weblate to translate other projects, such as [https://www.archivematica.org Archivematica].
# Go to: https://www.transifex.com/projects/p/atom
 
# Click the big "Translate" button
 
# Choose the language you want to work in, and the resource (e.g. AtoM 2.1, AtoM 2.2, etc)
 
 
</admonition>
 
</admonition>
  
Here's what the Translation Editor interface looks like - we've added some numbered orange circles to the image to point out different parts of the interface, which will be explained below.
+
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|Begin translating]].
 +
 
 +
[[File:weblate-preferences.png|frameless|500px|center|Weblate preferences settings page]]
  
[[File:transifex-translation-interface.png|thumb|700px|center|The Transifex Editor web interface]]
+
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.
  
 
<admonition type="seealso">
 
<admonition type="seealso">
Transifex documentation:
+
Weblate has its own help documentation - here's a help page on getting started:
* [http://docs.transifex.com/tutorials/txeditor/ Translating and reviewing content in the Transifex Editor]
+
 
* [http://docs.transifex.com/introduction/translators/ Getting started as a Translator]
+
* [https://docs.weblate.org/en/latest/user/profile.html Weblate Documentation]
 +
</admonition>
 +
 
 +
'''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.
 +
 
 +
[[File:first-login.png|frameless|500px|center|Weblate dashboard]]
 +
 
 +
===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 [https://www.accesstomemory.org 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.
 +
 
 +
[[File:weblate-components.png|frameless|500px|center|An example list of components available in the AtoM project]]
 +
 
 +
<admonition type="important">
 +
A lock icon appearing next to a component means that this component is not currently accepting new translations. This may be because Artefactual is in the process of updating the source strings, or because we are preparing the public AtoM release for that component. If you're ever unsure why a component is locked, feel free to contact us
 +
at translate@artefactual.com.
 
</admonition>
 
</admonition>
  
'''( 1 ) The language drop-down'''
+
===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:
 +
 
 +
[[File:request-language-tools.png|frameless|400px|center|Request new language]]
 +
 
 +
From the bottom of the page:
 +
 
 +
[[File:request-language.png|frameless|400px|center|Request new language]]
 +
 
 +
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.
 +
 
 +
[[File:request-language2.png|frameless|500px|center|Request a new language 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?".
 +
 
 +
<admonition type="tip">
 +
View a list of all languages supported in AtoM, with their corresponding language codes, here:
 +
 
 +
* [https://gist.github.com/sevein/d248525a66ef793c93d8 AtoM supported languages]
 +
</admonition>
  
This is where you can see what language you are currently working in. If you are working on translating AtoM into multiple languages (e.g. you have followed the steps above one time for each language, and have been added to the language teams), then you can also use this language drop-down to switch quickly between languages.
+
Complete the Weblate form with as much detail as possible using information from this list and click <code>Send</code>. Your request will be received by Artefactual.
  
'''( 2 ) Navigation panel - source strings'''
+
[[File:request-language3.png|frameless|500px|center|Language contact]]
  
The left-hand column of the page is the Navigation panel. It shows all the original source (English) strings to be translated on the farthest left. You can use the search bar above to search for a specific translation string (translation text keyword search), or you can search by a number of other filters, such as translated date (for strings that have already been translated), comments, etc.
+
<admonition type="important">
 +
Please review the options available in the list prior to requesting a new language! In many cases, we have had requests for different locales (for example, requesting "fr_FR" for France French, instead of working in the existing "fr" French project), but AtoM does not always support these very well. If at all possible, please work within the existing language options, or try to select the most generic option, without locale codes. We'll work with you if there are no other options, of course - but if you can avoid using a specific locale, it will make merging and maintaining your translations in AtoM much easier!
 +
</admonition>
  
[[File:transifex-search-bar.png|thumb|500px|center|The Transifex Editor's search bar, searching for specific text in the source strings]]
+
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.
  
You can also filter the source strings in the Navigation panel to show only those strings that have not yet been translated, using the buttons described in '''( 4 )''', below.
+
==Begin translating==
  
To translate a string, click on a source string in the navigation panel, and then perform your translation work in the middle column, the Translation panel described in '''( 5 )''', below.
+
'''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.
  
'''( 3 ) Navigation panel - translated strings'''
+
[[File:weblate-dashboard3.png|frameless|500px|center|Projects dashboard]]
  
Whenever content has already been translated by you or another Transifex user in your team, it will appear in grey to the right of the original source strings. You can re-edit translated content at any time by selecting a specific string, and then editing the existing translation using the middle column Translation panel, described in '''( 5 )''', below.
+
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.
  
'''( 4 ) Navigation filters'''
+
[[File:weblate-translation-links.png|frameless|500px|center|Translation overview page]]
  
These tabs allow you to quickly filter the content displayed in the left-hand column, the Navigation panel (described above). For example, you can use the middle filter to limit content in the Navigation panel so it displays only those strings that have not yet been translated. These tabs also offer you a measure of your team's progress - how many total strings there are, and how many have already been translated. If you have a team reviewer, you can also see at a glance how many strings have yet to be reviewed.
+
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.
  
 
<admonition type="tip">
 
<admonition type="tip">
Note as well that to the far right of the Navigation filters there is a progress bar, indicating how much of the source strings you have translated as a green progress indicator filling up the grey bar. If you hover this progress bar you can see further details.
+
Any of these filtered options available in the Overview page can also be reached directly from the translation
[[File:transifex-progress-bar.png|thumb|400px|center|The Transifex Editor's progress bar]]
+
interface, using the filter options available in the header:
 +
 
 +
[[File:weblate-strings-filter.png|frameless|500px|center|Translation page with strings filter shown]]
 
</admonition>
 
</admonition>
  
'''( 5 ) Translation panel'''
+
'''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.
 +
 
 +
[[File:full-editor-mode.png|frameless|500px|center|Full editor]]
 +
 
 +
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 [[#Become_a_reviewer|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:
  
The middle column on the page is where you will do the actual translation work. To start translating, you will first need to select a source string from the Navigation panel on the left (described above).
+
[[File:weblate-suggestions.png|frameless|500px|center|Automatic suggestions]]
  
The Translation panel is divided into 3 main sections. On the top is the source box, which contains the original source string you have selected in the Navigation panel on the left. In the middle is the translation box, where you can type in your translation of the source string. If the string is already translated, this box is filled in with the last translation, and the soure box will display in light grey the name of the user who last translated the string, and when. You can still make edits to the current translation if desired - simply click your cursor into the middle translation box, make your corrections, and click "Save." The bottom  of the Translation panel holds the context box, which includes some automated contextual information about the current string.
+
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.
  
 
<admonition type="important">
 
<admonition type="important">
Don't forget to click the Save button after you have entered a translation!  If you navigate to another source string, the translation stays in draft mode for as long as the editor is open and you are navigating on the same resource and translation language. If you save the translation before navigating to another source string, the translation is saved. There is a "Save all" button that will save all draft translations you've entered at once - but if you close the editor without saving your work, it will be lost!
+
 
 +
'''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:
 +
 
 +
[[File:weblate-variables.png|frameless|500px|center|Variables in a source string]]
 +
 
 +
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.
 +
 
 
</admonition>
 
</admonition>
  
'''( 6 ) Collaboration panel'''
 
  
The column on the right-hand side of the Transifex Editor offers a number of tools to support productivity and collaboration. It includes 4 different tabs:
+
'''8.''' When you have entered your translation, click one of the <code>Save</code> 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.
  
* '''Suggestions''' These are automated translation suggestions provided by Transifex, based on previously entered strings. Transifex also provides an indication of how much of a match it believes its suggestions are for the current string. Other users can also add suggestions, and members of your team can then use these, or vote on team member suggestions.
+
<admonition type="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 [https://docs.weblate.org/en/latest/user/checks.html#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.
  
[[File:transifex-suggestions.png|thumb|400px|center|Transifex machine-generated suggestions, based on previous translation work in the AtoM project]]
+
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.
  
<admonition type="seealso">
+
[[File:translation-states.png|frameless|500px|center|Example of an automatic suggestion from Weblate]]
Want to learn more about the automated Translation suggestions provided by Transifex in the Suggestions tab? They call it "Translation Memory." See:
+
 
* [http://docs.transifex.com/features/tm/ Translation Memory Introduction]
+
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 [[#Become_a_reviewer|Review]] below.
* [https://www.transifex.com/blog/2015/translation-memory-3-0/ Blog post: Translation Memory 3.0]
+
 
 +
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.
 +
</admonition>
 +
 
 +
'''9.''' For a faster translation workflow with a less cluttered interface, switch to '''Zen''' mode by clicking <code>Zen</code> 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.
 +
 
 +
[[File:edit-screen.png|frameless|500px|center|Adding Translations in Zen Mode]]
 +
 
 +
You can switch from Zen mode back to Full Editor mode by clicking <code>Exit Zen</code>.
 +
 
 +
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.
 +
 
 +
[[File:weblate-translation-fail.png|frameless|600px|center|Failed translation]]
 +
 
 +
<br />
 +
 
 +
You can work through the list of strings needing translation, choosing those you want to translate.
 +
 
 +
<admonition type="important">
 +
When you are entering translations in '''Zen''' mode, your entries will be saved automatically. When you are in '''Full editor''' mode, however, you need to save the translation in the primary language.
 
</admonition>
 
</admonition>
  
* '''History''': If previous translation work has been done on the currently selected string, the user name and date of the previous translations will be displayed in the History tab of the right-hand Collaboration panel.
+
'''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 <code>atom</code> (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:
* '''Glossary''': Glossary shows you any terms that have a pre-set translation. Thus far, we have not been using this feature in Transifex.
+
 
* '''Comments''': This allows you to collaborate with other users (across languages even!) and to ask for help if needed. Comments can be associated directly with a particular string, and posted either as a comment, or as an issue. Artefactual project maintainers get notifications about issues, so if you need further context for a string for example, feel free to comment as an issue (you will see the 2 options when you enter a comment - "Save", or "Save as issue") asking for clarification, and we will respond as soon as we can.
+
[[File:all-languages.png|frameless|500px|center|The All languages screen, sorted alphabetically by language]]
 +
 
 +
<admonition type="note">
 +
Weblate supports keyboard shortcuts to make navigating through the site quicker and more efficient. You can see a complete list of shortcuts [https://docs.weblate.org/en/latest/user/translating.html#keyboard-shortcuts here]. </admonition>
 +
 
 +
'''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 [https://translations.artefactual.com 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 [mailto:translate@artefactual.com translate@artefactual.com] so that we can grant you reviewer privileges.
  
There are other options and functions available within the Transifex Editor, but the above should provide you with the basics. To learn more, we suggest checking out some of the existing Transifex documentation:
+
'''14.''' Once you have reviewer privileges you can search for strings to be approved in your primary language(s). Click on <code>Strings waiting for review</code> from the translation overview screen in your chosen language. In Full editor mode this link appears in the list of String statuses:
  
* [http://docs.transifex.com/tutorials/txeditor/ Translating and reviewing content in the Transifex Editor]
+
[[File:waiting-for-review-full.png|frameless|500px|center|Strings needing approval]]
* [http://docs.transifex.com/introduction/translators/ Getting started as a Translator]
 
* [http://docs.transifex.com/faq/#what-are-the-web-editors-auxiliary-tools FAQ: What are the Web Editor's Auxiliary Tools?]
 
* [https://youtu.be/3y0x8q3Oj7Q Getting Started with Transifex (YouTube video)]
 
  
===Receive Notifications of Updates===
+
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):
  
One of the features Transifex provides is to allow translators to follow a specific project (e.g., AtoM)  This feature is called "watches" in Transifex. You can also configure several automatic notification settings for your account - if issues or comments are filed; if another user messages you, if there are changes in the source files for your project, etc.
+
[[File:waiting-for-review-zen.png|frameless|500px|center|Strings needing approval]]
  
'''To watch the AtoM project'''
+
For each string needing approval, you can click the radio button <code>Approved</code> to lock the translation for that string. Remember to click <code>Save</code> if you are using Full editor mode.
  
Navigate to the AtoM project page in Transifex (https://www.transifex.com/projects/p/atom/), and click the "Watch project" button on the right side of the menu bar at the top of the page.
+
'''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 [https://groups.google.com/g/ica-atom-users 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
  
[[File:transifex-watch-project.png|thumb|500px|center|The "Watch project" button on the AtoM project homepage in Transifex]]
+
==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.
  
You can always click this button again to stop watching the project.
+
[[File:string-example.png|frameless|500px|center|String with html coding]]
  
'''To configure your notification settings and your watches'''
+
If they do not appear in the translated string, we would ask reviewers to add them in before approving the translation.
  
In the top right corner of the the screen, located in the dark blue header bar at the top of the page, you will see your user name, followed by a little box with either a check mark, or a number in it. This second box is the notifications widget - if all notifications have been read, it will display a checkmark; if there are unread notifications, it will display the number of notifications to be reviewed.
+
'''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.
  
If you click on the notification widget, you will be taken to the notifications page of your user account:
+
[[File:FixStringError.png|frameless|500px|center|Prompt to fix string error]]
  
[[File:transifex-notifications.png|thumb|500px|center|The notifications page in Transifex, with the notification widget shown in the top right corner]]
+
Once the issue has been resolved then reviewers can proceed to finalizing and approving the translation.
  
On this page, you will see any activity notifications you have recieved, and the associated date. Just above these, you will see a link called "Notification settings." Click this to go to the Notification settings page of your account.
+
'''18.''' Weblate may throw up a warning saying that the translation provided in ‘Inconsistent’ See example below:
  
In the main tab, you can check or uncheck options for when you are notified (via the email you used to register your Transifex account, and via the notifications widget in the header bar). There is a second tab called "Watches" where you can review and control which projects and languages you are watching. Remember to save any changes you make!
+
[[File:InconsistentWarning.png|frameless|500px|center|Prompt to fix string error]]
  
[[File:transifex-notification-settings.png|thumb|500px|center|The notification settings page for your user account in Transifex.]]
+
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.
  
 
<admonition type="tip">
 
<admonition type="tip">
You can also get to this page by clicking on your user name, selecting Account settings from the drop-down menu, and then choosing "Notification settings" from the menu on the left. Note that in this area, you can also edit your user profile, change your email or password, and manage your connections to other accounts such as Facebook, Twitter, Github, etc - use the Account menu links on the left of the page to explore each accounts setting section.
+
We have a bit more information in the [[#FAQs|FAQ section below]], in case you still have questions!
 
</admonition>
 
</admonition>
  
===View project announcements===
+
==FAQs==
  
From time to time, we'll post an announcement about the status of a project. You can view these by going to the AtoM project homepage in Transifex (https://www.transifex.com/projects/p/atom/), and then clicking on the "Announcements" link in the light blue menu at the top of the page.
+
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:
  
[[File:transifex-announcements.png|thumb|500px|center|The announcements tab of the AtoM project in Transifex]]
+
* [https://docs.weblate.org/en/latest/user/basic.html Weblate basics]
 +
* [https://docs.weblate.org/en/latest/user/translating.html Translating using Weblate]
 +
* [https://docs.weblate.org/en/latest/faq.html Weblate: Frequently Asked Questions]
  
 
<admonition type="tip">
 
<admonition type="tip">
You can configure your notification settings so you receive an email whenever an announcement is posted. See the section above, [[Resources/Translation#Receive_Notifications_of_Updates|Receive Notifications of Updates]], for more information.
+
Have a question you don't see addressed here? Let us know via the AtoM [https://groups.google.com/g/ica-atom-users User Forum], or send us an email at [mailto:translate@artefactual.com translate@artefactual.com].
 
</admonition>
 
</admonition>
  
----
+
===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 [https://www.transifex.com/pricing/ 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 [https://github.com/artefactual/atom/ code repository] and [https://github.com/artefactual/atom-docs/ documentation], and going forward, the translation strings for each release will also be maintained in a separate [https://github.com/artefactual/atom-translations 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 [https://github.com/ GitHub] and [https://www.google.com/account/about/ 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.
 +
 
 +
<admonition type="important">
 +
If there are 2 open components in Weblate, then translations added to one component will '''not''' automatically be added to the other, even if it is for an earlier release. The only way to have your translations available in both components (and both releases) will be to manually add your translations to both components.
 +
 
 +
If there is a 2.7 and a 2.8 AtoM component in Weblate, then the 2.7 component will be used for a 2.7 minor release (i.e. 2.7.1, 2.7.2), and the 2.8 component will be used for the next major release (i.e. 2.8.0). In the case where there are 2 open components, those translation strings added in the earlier version will ''not'' be carried forward into the later component - but the later component ''will'' be used to create the next component in the future, meaning the strings will be carried forward into subsequent releases.
 +
</admonition>
 +
 
 +
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  [mailto:translate@artefactual.com 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 [mailto:translate@artefactual.com 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 [https://symfony.com/legacy 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:
  
'''Thank you''' for helping us translate AtoM - it is through your participation that we can make AtoM a truly international application!
+
* http://bit.ly/AtoM-langs
  
Got questions, or find something that's not covered here that you think would be helpful? Let us know via the AtoM [https://groups.google.com/forum/#!forum/ica-atom-users User Forum], or send us an email at [mailto:translate@artefactual.com translate@artefactual.com].
+
If it is supported, but you don't see it in Weblate, please see the [[#Requesting new languages|"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 [http://bit.ly/AtoM-langs here]), we'll approve it!
  
 +
See the documentation section [[Resources/Translation#Set_your_preferences|above]] for more details and screenshots.
  
 +
Alternatively, feel free to email us at [mailto:translate@artefactual.com 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 [https://groups.google.com/g/ica-atom-users User Forum], or send us an email at [mailto:translate@artefactual.com translate@artefactual.com].
  
  
Line 231: Line 437:
  
 
* [[Resources|Back to Resources]]
 
* [[Resources|Back to Resources]]
* [[Main Page|Back to AtoM wiki home]]
+
* [[Main_Page|AtoM wiki home]]
 
 
  
  
 
[[Category:Resources]]
 
[[Category:Resources]]

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.

Seealso

  • Interested in contributing to our project documentation? We have a separate page for that! See:Contribute documentation
  • Looking to contribute code to AtoM? See: Contribute code
  • Check out our User Manual for information on how to translate content or interface elements locally (in your installation only) - see the Multilingual section.
  • 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.

Log in to contribute to Artefactual translations

The AtoM project in Weblate lives here:


Login page

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:

Login page

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:

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.

Weblate's terms of service

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.

Configuring a local password in Weblate

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:

Configuring a local password in Weblate

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

An empty dashboard after creating a new account

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:

GitHub auth

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.

Authorization


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.

Weblate dashboard

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.

Weblate settings page

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.

Weblate languages settings page

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.

Weblate settings page

Tip

Don't see a language you would like to provide translations for? We have instructions on how you can request new languages in the section below!

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.

Weblate settings page

Tip

In the future, Artefactual hopes to use Weblate to translate other projects, such as Archivematica.

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.

Weblate preferences settings page

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.

Seealso

Weblate has its own help documentation - here's a help page on getting started:

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.

Weblate dashboard

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.

An example list of components available in the AtoM project

Important

A lock icon appearing next to a component means that this component is not currently accepting new translations. This may be because Artefactual is in the process of updating the source strings, or because we are preparing the public AtoM release for that component. If you're ever unsure why a component is locked, feel free to contact us at translate@artefactual.com.

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:

Request new language

From the bottom of the page:

Request new language

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.

Request a new language 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?".

Tip

View a list of all languages supported in AtoM, with their corresponding language codes, here:

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.

Language contact

Important

Please review the options available in the list prior to requesting a new language! In many cases, we have had requests for different locales (for example, requesting "fr_FR" for France French, instead of working in the existing "fr" French project), but AtoM does not always support these very well. If at all possible, please work within the existing language options, or try to select the most generic option, without locale codes. We'll work with you if there are no other options, of course - but if you can avoid using a specific locale, it will make merging and maintaining your translations in AtoM much easier!

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.

Projects dashboard

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.

Translation overview page

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:

Translation page with strings filter shown

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.

Full editor

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:

Automatic suggestions

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:

Variables in a source string

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.

Example of an automatic suggestion from Weblate

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.

Adding Translations in Zen Mode

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.

Failed translation


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

Important

When you are entering translations in Zen mode, your entries will be saved automatically. When you are in Full editor mode, however, you need to save the translation in the primary language.

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:

The All languages screen, sorted alphabetically by language

Note

Weblate supports keyboard shortcuts to make navigating through the site quicker and more efficient. You can see a complete list of shortcuts here.

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:

Strings needing approval

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):

Strings needing approval

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.

String with html coding

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.

Prompt to fix string error

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:

Prompt to fix string error

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.

Tip

We have a bit more information in the FAQ section below, in case you still have questions!

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:

Tip

Have a question you don't see addressed here? Let us know via the AtoM User Forum, or send us an email at translate@artefactual.com.

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.

Important

If there are 2 open components in Weblate, then translations added to one component will not automatically be added to the other, even if it is for an earlier release. The only way to have your translations available in both components (and both releases) will be to manually add your translations to both components.

If there is a 2.7 and a 2.8 AtoM component in Weblate, then the 2.7 component will be used for a 2.7 minor release (i.e. 2.7.1, 2.7.2), and the 2.8 component will be used for the next major release (i.e. 2.8.0). In the case where there are 2 open components, those translation strings added in the earlier version will not be carried forward into the later component - but the later component will be used to create the next component in the future, meaning the strings will be carried forward into subsequent releases.

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:

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:

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.