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
Conversation
Codecov Report
@@ 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.
|
docs/source/author/translations.rst
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
'changes' to 'change'
docs/source/author/translations.rst
Outdated
|
||
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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
docs/source/author/translations.rst
Outdated
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. |
There was a problem hiding this comment.
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.
docs/source/author/translations.rst
Outdated
|
||
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>`_. | ||
|
There was a problem hiding this comment.
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\:. |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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`_). |
There was a problem hiding this comment.
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'
There was a problem hiding this 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 ``_``). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
'python' to 'Python'
docs/source/author/topics.rst
Outdated
|
||
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``. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
'django' to 'Django'
docs/source/author/topics.rst
Outdated
- 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
'django' to 'Django'
docs/source/author/topics.rst
Outdated
|
||
.. raw:: html | ||
:file: ../_static/html_snippets/topics_content_directory_tree.html | ||
- Content markdown files |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
'markdown' to 'Markdown'
docs/source/author/topics.rst
Outdated
@@ -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>`__. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Double 'by'
docs/source/author/topics.rst
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
'markdown' to 'Markdown'
docs/source/author/topics.rst
Outdated
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. |
There was a problem hiding this comment.
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.
Fixes #681
Fixes #682