AtoM wiki - User contributions [en]

Resources/Documentation/Contribution guidelines

2022-12-06T14:42:06Z

Aseles: /* Contribution guidelines */

{{#pagetitle:Documentation contribution guidelines}}
[[Main Page]] > [[Resources]] > [[Resources/Documentation]] > Resources/Documentation/Contribution guidelines

This page offers a overview of best-practice suggestions for contributing documentation. We strongly recommend reviewing this page before contributing to the AtoM documentation - thanks! This document covers how to structure and format contributions to meet the established conventions of Sphinx, and of our documentation structure. For information on ''how'' you can contribute, see: [[Resources/Documentation/Contribute|Contribute documentation]].

<admonition type="seealso">
* [[Development/Contribute code|Contribute code]]
* [[Resources/Translation|Contribute translations]]
</admonition>

=Contribution guidelines=

So you're thinking of contributing to our documentation? See something that needs fixing, or something that could be improved? Great! Below you'll find some helpful guidelines to get you started, and to familiarize you with the approach we have been trying to follow.

In general, there are two main types of contributions:

* '''General improvements''': typo corrections, fixing broken refs or links, correcting inaccurate or out-of-date information, and offering better explanations through clearer writing and additional examples.
* '''New features or new pages''': Adding a page of documentation that we haven't yet covered in our ongoing rewrite attempts as we move platforms, or documenting a new feature that has been added to AtoM since the last release.

<admonition type="tip">
Looking for instructions on how you can contribute? Find them here:

* [[Resources/Documentation/Contribute|Contribute documentation]]

There are a number of ways you can help improve the documentation, even if you don't have the time to improve them yourself! These include:

* [[Resources/Documentation/Contribute#Suggest_minor_fixes_to_Artefactual|Suggesting minor fixes to Artefactal]]
* [[Resources/Documentation/Contribute#File_an_issue_in_our_documentation_repository|Filing an issue in our documentatoin repository]]
* [[Resources/Documentation/Contribute#Contribute_documentation_yourself_via_GitHub|Submitting a fix via GitHub's interface]]
* [[Resources/Documentation/Contribute#Set_up_a_local_environment_using_the_AtoM_Vagrant_box|Setting up a local environment using the AtoM Vagrant box]], and contributing changes using git
</admonition>

We welcome both kinds of contributions from our users, and are always aiming to improve our documentation as much and as often as possible. To maintain a sense of consistency and quality over time, here are a few tips.

===Before contributing===

'''1. Understand that our documents are all released under a Creative Commons Attribution-ShareAlike 4.0 license''' ([http://creativecommons.org/licenses/by-sa/4.0/ CC BY SA]). This means that your contributions are being released to Artefactual and the AtoM community to use, share, remix, and distribute as they see fit, provided any distribution takes place under the same licensing. Your work will be a gift to the AtoM user community, and we thank you for it!

'''2. Read through some of the documents we've already created'''. You'll notice that there is a consistent structure to most of them, which we will describe in greater detail below. By reading through some of our existing documentation, you will get a feeling for the overall structure and style. By looking at the source code (there's always a link to the source code in the sidebar), you can see how we've used [http://sphinx-doc.org/ Sphinx] to style and structure the page.

'''3. Familiarize yourself with Sphinx and reStructuredText before starting'''. As outlined above in our [[Resources/Documentation/About|About our documentation]] section of the wiki, we are using the [http://sphinx-doc.org/ Sphinx Python Documentation Generator] to produce the AtoM documentation. Sphinx employs [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructured Text] as its markup language, and you'll need to understand how to use its syntax if you want to contribute. The "First Steps with Sphinx" ([http://sphinx-doc.org/tutorial.html here]) is a great introduction to some of the key elements of Sphinx, and the reStructuredText Primer ([http://sphinx-doc.org/rest.html here]) will introduce you to the key characteristics of reST.

'''4. Examine the AtoM documentation glossary'''. Over the years, we have been adding to the glossary in our User Manual in an attempt to be consistent with how we refer to different parts of the application. You should try to use the same terms to refer to different parts of AtoM in your contributions, and you should link to the glossary (using the <code>:term:</code> reST markup) whenever possible - in general, we try to link a term the first time it is used in any paragraph. You can browse the current Glossary in our manuals here:

* https://www.accesstomemory.org/docs/latest/user-manual/glossary/glossary/

'''5. Make your contributions in the right place'''. Are you contributing to the latest version of our docs, so that these improvements will be carried forward in the next version? Are you looking to edit the Admin manual, but only able to find the User Manual? Learn more about the organization and structure of the documentation by carefully reviewing the section below, on [[Resources/Documentation/Contribution_guidelines#Structure_and_project_organization|Structure and project organiziation]].

'''6. Test your actions in an instance of AtoM before documenting them'''. We recommend following along step-by-step in AtoM as you create documentation, so that you can screenshot the process as you proceed, and so you don't miss any steps. If you find a bug in the software, don't document the bug - let us know! You can make a post in our [https://groups.google.com/forum/#!forum/ica-atom-users User Forum], or email us at [mailto:webmaster@artefactual.com webmaster@artefactual.com] to let us know, and we'll file a bug report and follow up on it.

==Structure and project organization==

The AtoM documentation consists of three manuals:

* The [https://www.accesstomemory.org/docs/latest/#user-manual User manual]
* The [https://www.accesstomemory.org/docs/latest/#administrator-manual Administrator manual]
* The [https://www.accesstomemory.org/docs/latest/#developer-s-manual Developer's manual]

These correspond to three top-level directories in the AtoM [https://github.com/artefactual/atom-docs documentation repository]

The manuals are meant to be stable. Changes at this level may also require layout changes to the documentation website. New top-level directories should not be added without first consulting Artefactual, who maintains the documentation. Generally, your contributions should have a place in one of these manuals - if you're not sure where, feel free to [mailto:webmaster@artefactual.com get in touch] with us directly, or make a post in our [https://groups.google.com/forum/#!forum/ica-atom-users User Forum].

We version our documentation with each major release (e.g. 2.3, 2.4, 2.5, etc), so users can look at the documentation most relevant to their local installation. In our documentation [https://github.com/artefactual/atom-docs code repository], this is represented as '''branches''', which you can see using the dropdown on the GitHub code repository page:

[[File:git-branch.png|center|385px|frameless| An image of the GitHub branch button]]

Inside each manual, contents are organized as Chapters and Pages. '''Chapters''' are represented as sub-directories within the parent manual directory, and generally correspond to the sections within each manual on the AtoM [https://www.accesstomemory.org/docs/latest/ documentation homepage]., For example, the User manual has chapters such as Overview, Getting started, Access content, Add/Edit content, etc.

[[File:docs-chapters.png|center|330px|frameless|An example of how the AtoM documentation is structured within a manual into chapters]]

Inside each Chapter, content is organized into '''Pages'''. Pages are individual reStructuredText documents, with an </code>.rst</code> extension.

[[File:doc-structure.png|center|350px|thumb|An example of how the AtoM documentation is structured within the repository]]

Pages can have sections, lead by section headers, which can be linked throughout the documentation where relevant. A detailed overview of how to structure pages, sections, and section headers will be provided below in the [[Resources/Documentation/Contribution_guidelines#Style_guide|Style guide]]. First, a more detailed overview of the full project structure.

[[File:docs-structure.png|left|240px|frameless|A detailed annotated image of how the AtoM documentation is structured]]

To the left is an annotated image of the AtoM documentation structure as seen in a [https://en.wikipedia.org/wiki/Source_code_editor text editor]. Below, you'll find a brief explanation of each element annotated in the structure image. Further details on how to work with each element will be included below, in the [[Resources/Documentation/Contribution_guidelines#Style_guide|Style guide]].

'''(1) - Main index''': The root <code>index.rst</code> file is the AtoM documentation homepage you see when navigating to:

* https://www.accesstomemory.org/docs/latest

Any time you add a new page to the AtoM documentation, make sure you also add a link in the appropriate manual's section to the main index, so user can find your new page and navigate to it.

'''(2) - The contents file''': This file acts as the master index for the project, telling Sphinx where to find all the manuals. At first glance, it doesn't contain much:

[[File:docs-contents.png|center|200px|frameless|An image of the contents.rst file in a text editor]]

However, this page uses the Sphinx <code>toctree</code> directive to provide the overall structure to our documentation. To understand the importance of this, we recommend you read up in the Sphinx documentation about documentation structure and the table of contents directive:

* [http://www.sphinx-doc.org/en/master/usage/quickstart.html#defining-document-structure Sphinx: Defining document structure]
* [http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive Spinx: The table of contents directive]

This table of contents is pointing to several other index files in the project - all the manuals have their own <code>index.rst</code> files, which contain a toctree for the pages in that manual. So this contents page tells Sphinx the overall project structure - it starts with index (our homepage), proceeds with the User manual (the toctree here points to the index.rst file in the user manual, which in turn has its own toctree for all the chapters and pages in the User mnanual, etc.), then the Administrator's manual, and finally with the Developer's manual.

'''(3) - The User manual index page:''' As mentioned above in '''(2)''', each manual has its own <code>index.rst</code> file inside the relevant manual direcotry, which contains a toctree for the pages in that manual. Note that the Admin manual, which was created by the Artefactual developers, is organized slightly differently: each chapter has its own sub-index (an <code>index.rst</code> file within each chapter directory) listing the the ordering of pages for that chapter, while the User manual's index file lists every page across chapters for the entire User manual. Because of this, the master index page for the Administrator manual (found at <code>admin-manual/index.rst</code>) is much shorter than the User manual index, because the toctree there just points to the individual chapter indices, which each have their own toctree for pages found in that specific chapter.

<admonition type="important">
If you don't list a new page in at least one of these toctrees, then you will get an error when you try to generate the documentation. Because Sphinx can output content in multiple formats - including linearly organized ones like a PDF - it needs to know the exact ordering of pages.
</admonition>

'''(4) - The User manual directory:''' This is an example of one of the master directories for an entire manual. All pages in the User manual appear in sub-directories (chapters) nested within this parent directory.

'''(5) - A chapter directory:''' This is an example of a chapter directory - a sub-directory of the manual to which it belongs. All pages in the "Access content" chapter of the User manual (such as Search, Browse, Advanced Search, Navigate, etc) appear as pages (individual reST documents) nested within the relevant chapter directory. For more information on working with Chapters, see the section below in the Style guide on [[Resources/Documentation/Contribution_guidelines#Chapters_and_Pages|Chapters and Pages]].

'''(6) - Chapter images sub-directory:''' Each chapter has its own images sub-directory. If you are adding an image to a new section of documentation, place the image in the images directory nested within the relevant chapter.

'''(7) - A page:''' Within each chapter you will find pages (individual reST files). All reST files should be nested within chapter directories, with the exception of the following:

* contents.rst - the top-level toctree for the AtoM documentation
* index.rst - the main index for the documentation, which acts as the homepage

For more information on working with Pages, see the section below in the Style guide on [[Resources/Documentation/Contribution_guidelines#Chapters_and_Pages|Chapters and Pages]].

'''(8) - The build directory:''' The_build directory is where your HTML or other formats will be output. This is where you will look on your local computer to preview your documentation locally before pushing. For example, when you run the command to generate HTML, there will be an html subdirectory inside of <code>_build</code>. If you open it in your local host computer's file explorer, you'll see the same structure of the docs, but with HTML pages instead of reStructured Text files. If you double-click to open one, it will open in your browser, where you can preview how your edits look before pushing them to the code repository.

==Style guide==

In order to keep our documentation consistent across manuals, we ask that you respect the following conventions and best practices when contributing documentation to the AtoM project. For information on '''how''' to contribute to the documentation, see:

* [[Resources/Documentation/Contribute|Contribute documenation]]

'''Jump to:'''

* [[Resources/Documentation/Contribution_guidelines#Maintain_an_80-character_width|Maintain an 80-character-width]]
* [[Resources/Documentation/Contribution_guidelines#Naming_conventions|Naming conventions]]
* [[Resources/Documentation/Contribution_guidelines#Chapters_and_Pages|Chapters and Pages]]
* [[Resources/Documentation/Contribution_guidelines#Sections|Sections]]
* [[Resources/Documentation/Contribution_guidelines#Links|Links]]
* [[Resources/Documentation/Contribution_guidelines#Images|Images]]
* [[Resources/Documentation/Contribution_guidelines#Admonitions|Admonitions]]
* [[Resources/Documentation/Contribution_guidelines#Writing_style|Writing style]]

===Maintain an 80-character width===

There is a long-standing convention in code writing to restrict the max width of a page's content to 80 characters. This dates back to the days in which this was the maximum width of a punch card, and the maximum display width of many early terminals. Those reasons no longer apply, as our technology has changed - but it also has to do with readability and the way the human eye/brain processes text, and how many people prefer to work with half-screen windows alongside the eventual output, for reference.

[[File:80char-width-example.png|center|500px|thumb|An example of how the AtoM documentation is hard wrapped to 80 characters.]]

For further information on this, see:

* http://www.richarddingwall.name/2008/05/31/is-the-80-character-line-limit-still-relevant/
* https://stackoverflow.com/questions/4651012/why-is-the-default-terminal-width-80-characters

When you are adding new content, be sure to keep to the 80 character width, please! If you are editing your files in a local text editor, there are settings and packages that can help you - for example, setting a veritcal ruler line at the 80-character mark; or installing hard wrapping package (such as [https://atom.io/packages/magic-reflow magic-reflow] for the [https://atom.io Atom] text editor, or [https://packagecontrol.io/packages/Wrap%20Plus WrapPlus] for [https://www.sublimetext.com/ Sublime Text]) that will allow you to hit a combination of keys and automatically wrap to the right length.

Code blocks are the one exception to this rule. A line of code can extend beyond 80 characters since reStructuredText will not be able to parse a mid-line break. This will generally only be relevant in the Administrator and Developer manuals.

===Naming conventions===

Whenever you are creating a new <code>.rst</code> file, saving a new image, or adding a new <code>:ref:</code> anchor label above a section heading, please use the following conventions:

* ''Make it human-readable'' - The label or file name should be as close as possible to the name of the file or section it refers to. You can exclude stop words such as prepositions etc, but the label name itself should be meaningful.
* ''Use lower case letters'' - We are not using capital letters, or camelCase, when naming files and labels.
* ''Separate words with hyphens'' - A file about "Archival descriptions" can be saved as <code>archival-descriptions.rst</code>
* ''Avoid special characters'' like stop words, exclude any special characters (such as <code>* $ ! &</code> etc) from names.

You can take a look in our AtoM documentation repository [https://github.com/artefactual/atom-docs here] to look at the raw reStructuredText markup for examples.

When naming titles and section headers, Use [https://en.wikipedia.org/wiki/Letter_case#Sentence_case sentence case] - that is, capitalize the first word only.

===Chapters and Pages===

The section above on [[Resources/Documentation/Contribution_guidelines#Structure_and_project_organization|Structure and project organiziation]] outlines how Chapters and Pages are used in the new project. It is unlikely that you will need to add a new Chapter - most new features occur within an already-defined workflow, and could be added to an existing chapter. If you think the AtoM documentation needs a new Chapter in one of its manuals, we recommend that you first [[Resources/Documentation/Contribute#File_an_issue_in_our_documentation_repository|file an issue in our documentation repository]] for discussion.

A Page is an individual reST file, or reStructuredText file. reST files end with the extension .rst. All reST files should be nested within chapter directories, with the exception of the following:

* contents.rst - the top-level toctree for the documentation
* index.rst - the main index for the documentation, which acts as the homepage

Make sure you have carefully reviewed the section above on [[Resources/Documentation/Contribution_guidelines#Structure_and_project_organization|Structure and project organiziation]] before adding a new page. New pages should follow the [[Resources/Documentation/Contribution_guidelines#Naming_conventions|naming conventions]] outlined above.

All pages should begin with an anchor, which acts as the linking mechanism for the page. Below the anchor there should be a title, which is title-cased and enclosed top and bottom by equals signs. Note that the equals signs should match the length of the title. The title should be followed by introductory text about the page.

<pre>
.. _my-great-page:

===================
My Great Page Title
===================

Introductory page text goes here.
</pre>

<admonition type="tip">
Read more about working with anchors and section headers in the Sphinx documentation:

* [http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections Sections]
* [http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role Internal anchor links ]
</admonition>

Whenever possible, try to keep all relevant content in a single page, organized into sections. For example, you will find all information about adding, editing, deleting, and linking archival descriptions in a single place - <code>archival-descriptions.rst</code>. By using the different section header levels of reST, we define a structure to the page that is automatically converted into a table of contents in the sidebar. This keeps the documentation's organization simpler, and there is less searching to find relevant or related information. Similarly, a simple structure will allow us to easily convert the HTML documentation into PDF and ePub formats in the future.

'''Starting with an introduction'''

We have tried to begin each page (and in some cases, each section) with an overview of the concepts, entities, and workflows involved in the chapter. See, for example, any of the pages in our User Manual's "Add/edit content" section. Check the User Manual Glossary for terms that can help you when doing this. We also like to refer to existing and relevant international standards, glossaries, articles, and other sources, such as:

* Any of the relevant standards of the International Council on Archives ([http://www.ica.org/10206/standards/standards-list.html ICA])
* The Society of American Archivists' [http://www2.archivists.org/glossary Glossary]
* The InterPARES 3 [http://interpares.org/ip3/ip3_terminology_db.cfm Terminology Database]
* Any of the ICA's [http://www.ciscra.org/mat/ Multilingual Archival Terminology Database] terms that can help guide you when doing this.

We are trying to make sure our documentation, and our AtoM development, is guided by relevant archival theory, standards, and best practices. Introducing these concepts is a great way to introduce a module in AtoM, and ensures that users understand not just how, but why. Close the introduction by offering a brief overview on how the outlined theory is implemented in AtoM, what can/cannot be done using the AtoM module, and what will be covered in the following section.

All pages should have a ''Back to the top'' link at the bottom of the page, which refers to the page anchor. Please remember to add one if you are adding a new page.

<pre>
:ref:`Back to the top <my-great-page>`
</pre>

===Sections===

To break up longer pages, use section headings. Section headings in reStructuredText are a single line of text (no line breaks!) with an underline adornment. Similar to the title, the underline adornment should match the length of the title. Section headings should be sentence-case.

Section headings should be preceded by an anchor, which are used to link to the section from anywhere else in the documentation, including this page's table of contents. All first-level headings should be listed in the table of contents and therefore require an anchor. Lower-level headings only require a heading if you would like to include them in the overall table of contents or link to them from anywhere else in the documentation. An example:

<pre>

.. _my-great-page:

===================
My Great Page Title
===================

Introductory page text goes here.

.. _first-level:

This is a first-level section
=============================

Information about this section.

A second-level section
----------------------

Detailed information about this subsection. Note that this section does not have
an anchor as we aren't going to link to it from anywhere else.

.. _another-first-level:

This is another first-level section
===================================

Detailed information about this subsection. Note that this section does not have
an anchor as we aren't going to link to it from anywhere else.

</pre>

reStructuredText allows you to use any non-alpha-numeric character for the underline adornment; however, pages must be internally consistent. The AtoM documentation has some inconsistencies across existing pages with the characters used for adornment, but going forward we will try to use the following:

* Title: === (overlined AND underlined)
* First-level heading: === (underline only)
* Second-level heading: ---
* Third-level heading: ^^^
* Fourth-level heading level: ###

===Table of contents===

Include a table of contents after the page's introductory text block, linking to the anchor for each major (i.e. first-level heading) section below. The AtoM documentation webpage will include a full table of contents for the page in a sidebar, but we want to give users a way to jump to the section most relevant to them. These types of tables of contents are built by hand. The table of contents should be preceded by the bolded phrase '''Jump to:''', or something similar such as " On this page you'll find," etc. An example:

<pre>

.. _my-great-page:

===================
My Great Page Title
===================

Introductory page text goes here.

**Jump to:**

* :ref:`This is a first-level section <first-level>`
* :ref:`This is another first-level section <another-first-level>`

.. _first-level:

This is a first-level section
=============================

Information about this section.

A second-level section
----------------------

Detailed information about this subsection. Note that this section does not have
an anchor as we aren't going to link to it from anywhere else.

.. _another-first-level:

This is another first-level section
===================================

Information about this section. This section has an anchor since it's a
first-level section that will be reflected in the table of contents.
</pre>

===Links===

There are three different types of links we use throughout the AtoM documentation: external links (to another page on the web), internal links (to another section of the documentation), and glossary links.

====External links====

There are two primary ways to create external [http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks hyperlinks in reST] - inline, and as hyperlink targets.

In the AtoM documentation we have previously used primarily inline links, but we are slowly converting all external links to use hyperlink targets, rather than embedded inline hyperlinks. This helps text blocks adhere to the 80-character limit, and also allows a link to be easily reused within a page.

Inline hyperlinks look like this:

<pre>
Here is a link to the `AtoM website <https://www.accesstomemory.org>`__
</pre>

Instead, going forward, style hyperlinks as a target, like so:

<pre>
Here is a link to the `AtoM website`_. You can also refer to documentation
about the `Sphinx documentation generator`_.
</pre>

At the very bottom of the page, create a list of external links. This list should be below the Back to the top link. This list does not need to adhere to the 80-character limit. You can reuse the target anchor throughout the page as needed, and it will automatically add the hyperlink to your text.

<pre>
.. _`AtoM website`: https://www.accesstomemory.org
.. _`Sphinx documentation generator`: http://www.sphinx-doc.org/en/master/index.html
</pre>

====Internal links====

To create a hyperlink to another section of the AtoM documentation, use a [http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role reference label] like this:

<pre>
For more information on navigation using the Add menu, see: :ref:`Add menu <main-menu-add>`.
</pre>

In the example above, main-menu-add is an anchor defined in another page from the same documentation repo - it's found in <code>navigate.rst</code>. Note that the display text can be different than the actual anchor target. If the Section header already contains the text you'd like to include, you can add a link without a label, like so:

<pre>
For more information on working with archival descriptions, see: :ref:`archival-descriptions`.
</pre>

When no display text is provided, Sphinx will automatically use the text of the related section title for display. In this case, it's the page title, which reads "Archival Descriptions" - suitable for our use without explicitly defining a different label.

Note that if necessary, you can also link to a page or section in the Archivematica documentation repositories. To do so, precede the anchor with either <code>archivematica:</code> or <code>storageservice:</code>. For example:

<pre>
For more information on uploading content from Archivematica into AtoM, see:
:ref:`Upload DIP <archivematica:upload-atom>` for more details.
</pre>

====Glossary links====

AtoM includes a lot of highly specific terminology and jargon - some comes from the archival profession, some from the development community and computer science, and some is AtoM-specific terminology we've developed to consistently refer to elements of the application and the user interface.

We want to make it easy for our users to find the content they need. Whenever you are using a term that appears in the glossary, use the <code>:term:</code> directive to link to it the first time it appers in a paragraph.

You can explore the current AtoM documentation glossary here:

* https://www.accesstomemory.org/docs/latest/user-manual/glossary/glossary/

Please familiarize yourself with it '''before''' you begin contributing, so you can refer to elements of the user interface consistently, and link to terms when relevant.

Term links work similarly to internal links in the documentation, except they don't need to follow the same naming conventions removing spaces:

<pre>
On loading, the :term:`edit page` will first display the record with all
:term:`information areas <information area>` closed.
</pre>

Generally, terms have been added to the glossary in the singular - so if you need to link a pluralized term, you'll want to add a label, e.g.

<pre>
Only :term:`administrators <administrator>` can access the Settings pages.
</pre>

If you need to add a new term to the Glossary, be sure to:

* Maintain the alphabetic ordering of the list
* Maintain the spacing and formatting of the page - otherwise you'll probably get an error when building
* Keep your explanation clear and as concise as possible
* Link to the most relevant section of documentation at the end of the definition whenever possible
* Include <code>:term:</code> links to any other terms you use in your definition, so users can easily navigate to them if needed

You can read more about working with Glossaries in Sphinx here:

* http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary-directive

===Images===

When possible, include a screenshot showing a key part of the action you are explaining that will help users understand AtoM's interface better. All images are placed in an "images" subdirectory that is shared by all pages in a chapter folder - for example, all pages in the ''Administer'' chapter's directory share a single images subdirectory. We prefer using PNG images, thanks!

Images '''must''' follow the [[Resources/Documentation/Contribution_guidelines#Naming_conventions|naming conventions]] outlined above - spaces or special characters used in image names will cause errors during the build.

Here is an example of an image added in the AtoM documentation:

<pre>
.. image:: images/description-collapsed.*
:align: center
:width: 85%
:alt: An archival description with all information areas closed
</pre>

Center-aligned images will display as a block (so text is broken above/below, and does not flow around it), while images aligned left or right will float, so that text wraps around them. If you are aligning an image to the left or right, you probably don't want a width above %50.

Please always add a description of the image using the alt attribute, to better support screen readers and give users a sense of what they are supposed to see if an image is broken or missing.

Note that an asterisk is used in place of the actual image file extension when using the image directive in reST.

If you want to include a caption with an image, use the figure directive - here's an example from the [https://www.accesstomemory.org/docs/latest/user-manual/access-content/navigate/ Navigate] page:

<pre>
.. figure:: images/breadcrumb-archdesc.*
:align: center
:figwidth: 80%
:width: 100%
:alt: An image of breadcrumb trail on an archival description

An example of a breadcrumb trail (below the title bar)
on a lower-level archival description
</pre>

With Figures, the width attribute should remain at 100% - it's the figwidth attribute that determines the width the image will occupy on your page. The caption text appears after a full line break below the attributes, and in line with them.

If you are including images external to AtoM, make sure that you have permission to use and share the content you screenshot!

You'll also find some basic help on working with images in Sphinx [http://sphinx-doc.org/rest.html#images here], and figures are covered in more depth in the reStructured Text documenation [http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure here].

===Admonitions===

Sphinx and reST include a whole class of built-in [http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions admonitions], and we have styled several of these for inclusion in the documentation as necessary (we use the same ones in the wiki here as well). Here are some examples:

<admonition type="note">
This is a note. We often use them to point out things like, "you must be logged in and have sufficient edit permissions to perform this action. See: User roles."
</admonition>

<admonition type="tip">
We use Tips to offer alternative workflows, handy links and reminders, or useful insights into the current instructions.
</admonition>

<admonition type="important">
Use an Important admonition to make sure a user is aware of a key step, or understands the consequences of an action.
</admonition>

<admonition type="warning">
Warnings are used when an action will have irreversible consequences, such as deleting a record - or occasionally to mention a known bug, if we think it might be a while before we are able to resolve the issue.
</admonition>

Here are a couple examples of admonitions as they appear in the source reST files in the AtoM documentation:

<pre>
.. SEEALSO::

* :ref:`archival-institutions`
* :ref:`edit-institution-theme`
* :ref:`ISDIAH template <isdiah-template>`
* :ref:`link-archival-institution`
</pre>

<pre>
.. WARNING::

Deleting a description is a permanent operation that cannot be undone, and
the associated data will be removed from AtoM's database. Be sure that you
want to delete a record before confirming the operation.
</pre>

===Writing style===

Try to keep your writing clear and concise. Your explanations should be comprehensive, but easy to follow. The more precise your writing is, the easier others will find it to follow. We also hope to have our documentation translated into multiple languages in the future - keeping it simple and to the point will reduce the workload in the translation process.

Here are some general guidelines and reminders for tone and style:

* Write accessibly in clear, simple sentences intended for a global audience. Avoid colloquial language, humour, cultural references, and personal opinion. Keep your writing technical.
* Write from a second-person point of view. Use "you" and "your", not "my", "our", or "their".
* Avoid jargon and acronyms, if you can. Spell out acronyms at least once per page.
* Remember to link to glossary terms when first introducing them in a paragraph.
* Be consistent. Use the same consistently-formatted word or phrase for a concept throughout the documentation.
* Don't qualify or prejudge actions. Don't write that something is "easy" or "quick" as this is a deterrent if the user is not able to complete the action.
* Don't reference future development or features that don't yet exist.
* Remember to use sentence case for page titles and section headings.
* Use numbered lists for actions that happen in sequence.
* Use bulleted lists for most other lists.
* Truncate lines after 80 characters - more on this [[Resources/Documentation/Contribution_guidelines#Maintain_an_80-character_width|above]]
* Use serial (Oxford) commas (preferred, not enforced).

==Questions?==

If there's something that you're not clear about in these instructions, or you've run into an unexpected error, send us an email at [mailto:webmaster@artefactual.com webmaster@artefactual.com], or make a post in the AtoM [https://groups.google.com/forum/#!forum/ica-atom-users User Forum]!

<admonition type="seealso">
* [[Resources/Documentation/About|About the AtoM documentation]]
* [[Resources/Documentation/Contribute|Contribute documentation]]
* [[Development/Contribute code|Contribute code]]
* [[Resources/Translation|Contribute translations]]
* [[Resources/User forum|Using the AtoM User Forum]]
* [[Resources/Issue tracker|Using the AtoM Issue tracker]]
</admonition>

[[#Resources/Documentation/Contribution_guidelines|Back to top]]

-----

* [[Resources/Documentation|Back to Documentation]]
* [[Resources|Back to Resources]]
* [[Main Page|AtoM wiki home]]

[[Category:Resources]]

File:FixStringError.png

2022-10-07T19:23:17Z

Aseles:

Resources/Translation

2022-10-07T19:22:59Z

Aseles: /* Become a reviewer */

{{#pagetitle:Contribute translations}}
[[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, [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 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">
* 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]]
* 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>

__TOC__

==Log in to contribute to Artefactual translations==

'''The AtoM project in Weblate lives here:'''

* https://translations.artefactual.com/

 

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

* 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.

[[File:weblate-tos.png|frameless|600px|center|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.

[[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.

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

[[File:weblate-local-pass.png|frameless|600px|center|Configuring a local password in Weblate]]

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

[[File:weblate-dash-empty.png|frameless|600px|center|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:

[[File:weblate-github.png|frameless|300px|center|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.

[[File:qubot-authorization.png|frameless|300px|center|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.

[[File:first-login.png|frameless|500px|center|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.

[[File:weblate-settings-link.png|frameless|500px|center|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.

[[File:weblate-language-tab.png|frameless|500px|center|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.

[[File:weblate-lang-menu.png|frameless|500px|center|Weblate settings page]]

<admonition type="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 [[#Requesting new languages|below]]!
</admonition>

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.

[[File:weblate-watched-projects.png|frameless|500px|center|Weblate settings page]]

<admonition type="tip">
In the future, Artefactual hopes to use Weblate to translate other projects, such as [https://www.archivematica.org Archivematica].
</admonition>

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]]

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">
Weblate has its own help documentation - here's a help page on getting started:

* [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>

===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>

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.

[[File:request-language3.png|frameless|500px|center|Language contact]]

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

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.

[[File:weblate-dashboard3.png|frameless|500px|center|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.

[[File:weblate-translation-links.png|frameless|500px|center|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.

<admonition type="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:

[[File:weblate-strings-filter.png|frameless|500px|center|Translation page with strings filter shown]]
</admonition>

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

[[File:weblate-suggestions.png|frameless|500px|center|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.

<admonition type="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:

[[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>

'''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.

<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.

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.

[[File:translation-states.png|frameless|500px|center|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 [[#Become_a_reviewer|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.
</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]]

 

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>

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

[[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.

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

[[File:waiting-for-review-full.png|frameless|500px|center|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):

[[File:waiting-for-review-zen.png|frameless|500px|center|Strings needing approval]]

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.

'''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

==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.

[[File:string-example.png|frameless|500px|center|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.

[[File:FixStringError.png|frameless|500px|center|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:

[[File:InconsistentWarning.png|frameless|500px|center|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.

<admonition type="tip">
We have a bit more information in the [[#FAQs|FAQ section below]], in case you still have questions!
</admonition>

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

* [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">
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>

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

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

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].

-----

* [[Resources|Back to Resources]]
* [[Main_Page|AtoM wiki home]]

[[Category:Resources]]

Resources/Translation

2022-10-07T19:22:35Z

Aseles: /* Reviewing Translations */

{{#pagetitle:Contribute translations}}
[[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, [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 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">
* 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]]
* 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>

__TOC__

==Log in to contribute to Artefactual translations==

'''The AtoM project in Weblate lives here:'''

* https://translations.artefactual.com/

 

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

* 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.

[[File:weblate-tos.png|frameless|600px|center|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.

[[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.

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

[[File:weblate-local-pass.png|frameless|600px|center|Configuring a local password in Weblate]]

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

[[File:weblate-dash-empty.png|frameless|600px|center|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:

[[File:weblate-github.png|frameless|300px|center|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.

[[File:qubot-authorization.png|frameless|300px|center|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.

[[File:first-login.png|frameless|500px|center|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.

[[File:weblate-settings-link.png|frameless|500px|center|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.

[[File:weblate-language-tab.png|frameless|500px|center|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.

[[File:weblate-lang-menu.png|frameless|500px|center|Weblate settings page]]

<admonition type="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 [[#Requesting new languages|below]]!
</admonition>

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.

[[File:weblate-watched-projects.png|frameless|500px|center|Weblate settings page]]

<admonition type="tip">
In the future, Artefactual hopes to use Weblate to translate other projects, such as [https://www.archivematica.org Archivematica].
</admonition>

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]]

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">
Weblate has its own help documentation - here's a help page on getting started:

* [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>

===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>

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.

[[File:request-language3.png|frameless|500px|center|Language contact]]

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

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.

[[File:weblate-dashboard3.png|frameless|500px|center|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.

[[File:weblate-translation-links.png|frameless|500px|center|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.

<admonition type="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:

[[File:weblate-strings-filter.png|frameless|500px|center|Translation page with strings filter shown]]
</admonition>

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

[[File:weblate-suggestions.png|frameless|500px|center|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.

<admonition type="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:

[[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>

'''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.

<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.

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.

[[File:translation-states.png|frameless|500px|center|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 [[#Become_a_reviewer|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.
</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]]

 

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>

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

[[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.

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

[[File:waiting-for-review-full.png|frameless|500px|center|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):

[[File:waiting-for-review-zen.png|frameless|500px|center|Strings needing approval]]

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.

'''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

Reviewing translations
==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.

[[File:string-example.png|frameless|500px|center|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.

[[File:FixStringError.png|frameless|500px|center|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:

[[File:InconsistentWarning.png|frameless|500px|center|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.

<admonition type="tip">
We have a bit more information in the [[#FAQs|FAQ section below]], in case you still have questions!
</admonition>

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

* [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">
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>

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

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

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].

-----

* [[Resources|Back to Resources]]
* [[Main_Page|AtoM wiki home]]

[[Category:Resources]]

File:InconsistentWarning.png

2022-10-07T19:19:23Z

Aseles:

File:FixStringError.jpg

2022-10-07T19:16:17Z

Aseles:

Resources/Translation

2022-10-07T19:15:04Z

Aseles: /* Become a reviewer */

{{#pagetitle:Contribute translations}}
[[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, [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 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">
* 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]]
* 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>

__TOC__

==Log in to contribute to Artefactual translations==

'''The AtoM project in Weblate lives here:'''

* https://translations.artefactual.com/

 

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

* 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.

[[File:weblate-tos.png|frameless|600px|center|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.

[[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.

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

[[File:weblate-local-pass.png|frameless|600px|center|Configuring a local password in Weblate]]

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

[[File:weblate-dash-empty.png|frameless|600px|center|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:

[[File:weblate-github.png|frameless|300px|center|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.

[[File:qubot-authorization.png|frameless|300px|center|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.

[[File:first-login.png|frameless|500px|center|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.

[[File:weblate-settings-link.png|frameless|500px|center|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.

[[File:weblate-language-tab.png|frameless|500px|center|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.

[[File:weblate-lang-menu.png|frameless|500px|center|Weblate settings page]]

<admonition type="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 [[#Requesting new languages|below]]!
</admonition>

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.

[[File:weblate-watched-projects.png|frameless|500px|center|Weblate settings page]]

<admonition type="tip">
In the future, Artefactual hopes to use Weblate to translate other projects, such as [https://www.archivematica.org Archivematica].
</admonition>

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]]

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">
Weblate has its own help documentation - here's a help page on getting started:

* [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>

===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>

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.

[[File:request-language3.png|frameless|500px|center|Language contact]]

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

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.

[[File:weblate-dashboard3.png|frameless|500px|center|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.

[[File:weblate-translation-links.png|frameless|500px|center|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.

<admonition type="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:

[[File:weblate-strings-filter.png|frameless|500px|center|Translation page with strings filter shown]]
</admonition>

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

[[File:weblate-suggestions.png|frameless|500px|center|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.

<admonition type="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:

[[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>

'''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.

<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.

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.

[[File:translation-states.png|frameless|500px|center|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 [[#Become_a_reviewer|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.
</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]]

 

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>

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

[[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.

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

[[File:waiting-for-review-full.png|frameless|500px|center|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):

[[File:waiting-for-review-zen.png|frameless|500px|center|Strings needing approval]]

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.

'''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

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.

[[File:string-example.png|frameless|500px|center|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.

[[File:FixStringError.png|frameless|500px|center|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:

[[File:InconsistentWarning.png|frameless|500px|center|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.

<admonition type="tip">
We have a bit more information in the [[#FAQs|FAQ section below]], in case you still have questions!
</admonition>

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

* [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">
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>

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

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

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].

-----

* [[Resources|Back to Resources]]
* [[Main_Page|AtoM wiki home]]

[[Category:Resources]]

Resources/Translation

2022-10-07T19:00:03Z

Aseles: /* Begin translating */

{{#pagetitle:Contribute translations}}
[[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, [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 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">
* 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]]
* 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>

__TOC__

==Log in to contribute to Artefactual translations==

'''The AtoM project in Weblate lives here:'''

* https://translations.artefactual.com/

 

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

* 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.

[[File:weblate-tos.png|frameless|600px|center|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.

[[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.

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

[[File:weblate-local-pass.png|frameless|600px|center|Configuring a local password in Weblate]]

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

[[File:weblate-dash-empty.png|frameless|600px|center|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:

[[File:weblate-github.png|frameless|300px|center|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.

[[File:qubot-authorization.png|frameless|300px|center|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.

[[File:first-login.png|frameless|500px|center|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.

[[File:weblate-settings-link.png|frameless|500px|center|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.

[[File:weblate-language-tab.png|frameless|500px|center|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.

[[File:weblate-lang-menu.png|frameless|500px|center|Weblate settings page]]

<admonition type="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 [[#Requesting new languages|below]]!
</admonition>

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.

[[File:weblate-watched-projects.png|frameless|500px|center|Weblate settings page]]

<admonition type="tip">
In the future, Artefactual hopes to use Weblate to translate other projects, such as [https://www.archivematica.org Archivematica].
</admonition>

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]]

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">
Weblate has its own help documentation - here's a help page on getting started:

* [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>

===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>

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.

[[File:request-language3.png|frameless|500px|center|Language contact]]

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

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.

[[File:weblate-dashboard3.png|frameless|500px|center|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.

[[File:weblate-translation-links.png|frameless|500px|center|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.

<admonition type="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:

[[File:weblate-strings-filter.png|frameless|500px|center|Translation page with strings filter shown]]
</admonition>

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

[[File:weblate-suggestions.png|frameless|500px|center|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.

<admonition type="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:

[[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>

'''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.

<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.

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.

[[File:translation-states.png|frameless|500px|center|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 [[#Become_a_reviewer|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.
</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]]

 

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>

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

[[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.

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

[[File:waiting-for-review-full.png|frameless|500px|center|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):

[[File:waiting-for-review-zen.png|frameless|500px|center|Strings needing approval]]

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.

'''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.

<admonition type="tip">
We have a bit more information in the [[#FAQs|FAQ section below]], in case you still have questions!
</admonition>

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

* [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">
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>

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

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

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].

-----

* [[Resources|Back to Resources]]
* [[Main_Page|AtoM wiki home]]

[[Category:Resources]]

File:String-example.png

2022-10-07T18:57:28Z

Aseles:

Resources/Translation

2022-10-07T18:56:36Z

Aseles: /* Begin translating */

{{#pagetitle:Contribute translations}}
[[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, [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 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">
* 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]]
* 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>

__TOC__

==Log in to contribute to Artefactual translations==

'''The AtoM project in Weblate lives here:'''

* https://translations.artefactual.com/

 

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

* 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.

[[File:weblate-tos.png|frameless|600px|center|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.

[[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.

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

[[File:weblate-local-pass.png|frameless|600px|center|Configuring a local password in Weblate]]

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

[[File:weblate-dash-empty.png|frameless|600px|center|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:

[[File:weblate-github.png|frameless|300px|center|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.

[[File:qubot-authorization.png|frameless|300px|center|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.

[[File:first-login.png|frameless|500px|center|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.

[[File:weblate-settings-link.png|frameless|500px|center|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.

[[File:weblate-language-tab.png|frameless|500px|center|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.

[[File:weblate-lang-menu.png|frameless|500px|center|Weblate settings page]]

<admonition type="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 [[#Requesting new languages|below]]!
</admonition>

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.

[[File:weblate-watched-projects.png|frameless|500px|center|Weblate settings page]]

<admonition type="tip">
In the future, Artefactual hopes to use Weblate to translate other projects, such as [https://www.archivematica.org Archivematica].
</admonition>

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]]

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">
Weblate has its own help documentation - here's a help page on getting started:

* [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>

===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>

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.

[[File:request-language3.png|frameless|500px|center|Language contact]]

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

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.

[[File:weblate-dashboard3.png|frameless|500px|center|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.

[[File:weblate-translation-links.png|frameless|500px|center|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.

<admonition type="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:

[[File:weblate-strings-filter.png|frameless|500px|center|Translation page with strings filter shown]]
</admonition>

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

[[File:weblate-suggestions.png|frameless|500px|center|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.

<admonition type="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:

[[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>

'''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.

<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.

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.

[[File:translation-states.png|frameless|500px|center|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 [[#Become_a_reviewer|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.
</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]]

 

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>

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

[[File:all-languages.png|frameless|500px|center|The All languages screen, sorted alphabetically by language]]

<admonition type="important">
"'Maintaining the string"'
There are some strings for translations that contain coding in them - an example would be:

[[File:string-example.png|frameless|500px|center|Example string with coding]]

These types of notations in the translations are meant to indicate variables that AtoM will swap with current actual values when displaying the string to users. In the above example, AtoM would substitute these variables with the actual version number of the available upgrade when displaying the message to users. Therefore, whenever such coding appears in the original English string, please make sure that it is replicated in the translation. </admonition>

<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.

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

[[File:waiting-for-review-full.png|frameless|500px|center|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):

[[File:waiting-for-review-zen.png|frameless|500px|center|Strings needing approval]]

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.

'''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.

<admonition type="tip">
We have a bit more information in the [[#FAQs|FAQ section below]], in case you still have questions!
</admonition>

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

* [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">
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>

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

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

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].

-----

* [[Resources|Back to Resources]]
* [[Main_Page|AtoM wiki home]]

[[Category:Resources]]