Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Translation Documentation #748

Merged
merged 10 commits into from Dec 12, 2017
Merged

Translation Documentation #748

merged 10 commits into from Dec 12, 2017

Conversation

jordangriffiths01
Copy link
Contributor

Fixes #681
Fixes #682

@codecov
Copy link

codecov bot commented Dec 12, 2017

Codecov Report

Merging #748 into develop will not change coverage.
The diff coverage is n/a.

Impacted file tree graph

@@           Coverage Diff           @@
##           develop    #748   +/-   ##
=======================================
  Coverage     99.4%   99.4%           
=======================================
  Files           93      93           
  Lines         3047    3047           
  Branches       373     373           
=======================================
  Hits          3029    3029           
  Misses           8       8           
  Partials        10      10

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update de3e7ef...d9d63c5. Read the comment docs.

be implemented for the ``1.0.0`` release in late 2017.
.. note::
This guide is a work in progress, as translation support for CS Unplugged is a recent addition.
Many of the finer details of the translation workflow are likely to changes as translators begin to work on the project.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'changes' to 'change'


1. Read this documentation page, especially the `Translation Notes`_ section.
2. Create an account on `Crowdin <https://crowdin.com/join>`__.
3. Read the Crowdin `documentation <https://support.crowdin.com/crowdin-intro/>`_ for translators.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page seemed unnecessary, should we skip this step?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough - I actually meant to link to https://support.crowdin.com/online-editor/ which is more relevant. But that's listed below anyway, so I've removed this step.

Crowdin Overview
==============================================================================
We use a localisation management platform called `Crowdin <https://crowdin.com/project/cs-unplugged>`__ for translation of CS Unplugged.
Our project is public, meaning that anyone can create an account and contribute translations.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this true, or is the Crowdin project still locked down?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is true, it got opened up a while back

These raw text tags will never be visible in the final release, as they are parsed and removed during verto processing.

For technical reasons, any changes in the translation of a verto tag will not be rendered in-context translation mode, and will only be visible after the translated file is downloaded for release.
See `here <../developer/translation_infrastructure.html#in-context-translation>`_ for more details.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Internal documentation links should not use the link syntax. It's ref or something similar.


In cases where in-context translation mode is not available, it is also possible to use the standard Crowdin UI.
To access this, visit the CS Unplugged project page on `Crowdin <https://crowdin.com/project/cs-unplugged>`_.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extra whitespace around this comment.

Translation Principles
=============================================================================

The following principles were used to guide the design of a translation system for CS Unplugged\:.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extra characters at the end of this line.


Translatable Files
=============================================================================
Translatable content is stored in two types of files:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Translatable content is also stored in HTML and Python files.

Django Package - ``modeltranslation``
******************************************************************************
The django modeltranslation package is utilised to stored translated content on a model.
The basic idea is that for each translatable field, an extra database column is added for every language defined in the django settings file.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'django' to 'Django'


.. note::

The default behaviour for modeltranslation is to fallback to the english value if no translation is present.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'modeltranslation' should be within code tags, and 'english' to 'English'

.. note::

The default behaviour for modeltranslation is to fallback to the english value if no translation is present.
In CS Unplugged, this is desirable for fields such as name and title, but is often undesirable for most other fields (see `Translation Principles`_).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'this is desirable for fields' to 'this is desirable for text fields'

Copy link
Member

@JackMorganNZ JackMorganNZ left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking awesome, just small fixes.

@@ -50,6 +52,11 @@ Both types of file are stored inside the directory tree for a given language (ie

These files can be parsed and loaded using a `utility function <UtilityFunctions_>`_ on the ``TranslatableModelLoader`` base class.

For the latter two type of files, Django's built-in `translation support <https://docs.djangoproject.com/en/2.0/topics/i18n/>`_ is utilised to handle translatable strings.
In python code, text is wrapped in a ``ugettext`` function call (usually aliased to ``_``).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'python' to 'Python'


All files live inside the ``topics/content`` directory.
The first two files are unique for each translation language, and are stored in a directory tree specific to that language.
This directory is named using the languages django locale code eg. ``en``, ``de_AT``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'django' to 'Django'

- Blue is directories.
- Red is YAML configuration files (see :doc:`understanding_configuration_files`).
- Green is Markdown text files.
- a directory for each language in which content exists, named using the django locale code. This directory contains
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'django' to 'Django'


.. raw:: html
:file: ../_static/html_snippets/topics_content_directory_tree.html
- Content markdown files
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'markdown' to 'Markdown'

@@ -1,6 +1,10 @@
Topic Content
##############################################################################

.. warning::
All flowcharts in this guide need to be updated to reflect changes to the content directory structure.
This is tracked by by `isssue/749 <https://github.com/uccser/cs-unplugged/issues/749>`__.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Double 'by'

These files live under a special ``structure`` directory.

As a simple rule, structure files situated inside the ``structure`` directory contain **no** user facing text.
Any user facing text lives in either a markdown file or a YAML translation file inside the locale specific directories.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'markdown' to 'Markdown'

Configuration files are shared amongst all languages, because the content structure is the same for all languages.
These files live under a special ``structure`` directory.

As a simple rule, structure files situated inside the ``structure`` directory contain **no** user facing text.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional: Would be simpler to phrase it as below?

'directory contain no text a website user will see.

@jordangriffiths01 jordangriffiths01 merged commit c2781cd into develop Dec 12, 2017
@jordangriffiths01 jordangriffiths01 deleted the i18n-docs branch December 12, 2017 20:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation internationalization Related to translating the website
Development

Successfully merging this pull request may close these issues.

None yet

2 participants