Skip to content

C
converse.js
Commit 6e02cf49 authored by Michal Čihař's avatar Michal Čihař
Browse files
Options

Move project setup to separate chapter

parent 0d2e443f
Hide whitespace changes
Inline Side-by-side
Showing with 227 additions and 224 deletions
docs/admin/admin.rst
View file @ 6e02cf49
...@@ -4,230 +4,6 @@ Administration ...@@ -4,230 +4,6 @@ Administration
Administration of Weblate is done through standard Django admin interface, Administration of Weblate is done through standard Django admin interface,
which is available under :file:`/admin/` URL. which is available under :file:`/admin/` URL.
Translation organization
------------------------
Weblate organizes translatable content into tree like structure. The toplevel
object is :ref:`project`, which should hold all translations which belong
together (for example translation of an application in several versions
and/or documentation). On the next level, there is :ref:`subproject`, which is
actually the resource to translate. Here you define Git repository to use and
mask of files to translate. Bellow :ref:`subproject` there are individual
translations, which are handled automatically by Weblate as the translation
files (matching mask defined in :ref:`subproject`) appear in Git repository.
Adding new resources
--------------------
All translation resources need to be available as Git repositories and are
organized as project/subproject structure.
Weblate supports wide range of translation formats supported by translate
toolkit, see :ref:`formats` for more information.
.. _monolingual:
Monolingual resources
+++++++++++++++++++++
Weblate does support both multilingual and monolingual formats. For easier
translating of monolingual formats, you should provide template file, which
contains mapping of message IDs to source language (usually English).
.. _project:
Project
-------
To add new resource to translate, you need to create translation project first.
The project is sort of shelf, in which real translations are folded. All
subprojects in same project share suggestions and dictionary, also the
translations are automatically propagated through the all subproject in single
project (unless disabled in subproject configuration).
The project has only few attributes giving translators information about
project.
Commit message
++++++++++++++
The commit message on each commit Weblate does, it can use following format
strings in the message:
``%(language)s``
Language code
``%(language_name)s``
Language name
``%(subproject)s``
Subproject name
``%(project)s``
Project name
``%(total)s``
Total strings count
``%(fuzzy)s``
Fuzzy strings count
``%(fuzzy_percent)s``
Fuzzy strings percent
``%(translated)s``
Translated strings count
``%(translated_percent)s``
Translated strings percent
Adjusting interaction
+++++++++++++++++++++
There are also additional features which you can control, like automatic
pushing of changes (see also :ref:`push-changes`), merge or rebase
(see :ref:`merge-rebase`), git committer name or
maintaining of Translation-Team header.
.. _subproject:
Subproject
----------
Subproject is real resource for translating. You enter Git repository location
and file mask which files to translate and Weblate automatically fetches the Git
and finds all matching translatable files.
Should the language definition for translation be missing, empty definition is
created and named as "cs_CZ (generated)". You should adjust the definition and
report this back to Weblate authors so that missing language can be included in
next release.
The subproject contains all important parameters for working with Git and
getting translations out of it:
Repo
Git repository used to pull changes.
This can be either real Git URL or ``weblate://project/subproject``
indicating that Git repository should be shared with another subproject.
Push
Git URL used for pushing, this is completely optional and push support will
be disabled when this is empty.
Repoweb
URL of repository browser to display source files (location where messages
are used). When empty no such links will be generated.
For example on GitHub, you would use something like ``https://github.com/nijel/weblate-hello/blob/%(branch)s/%(file)s#L%(line)s``.
Branch
Which branch to checkout from the Git and where to look for translations.
Filemask
Mask of files to translate including path. It should include one *
replacing language code. In case your Git repository contains more than one
translation files (eg. more Gettext domains), you need to create separate
subproject for each. For example ``po/*.po`` or
``locale/*/LC_MESSAGES/django.po``.
Monolingual base language file
Base file containing strings definition for :ref:`monolingual`.
Base file for new translations
Base file used to generate new translations, eg. ``.pot`` file with Gettext.
Report source bugs
Email address used for reporting upstream bugs. This address will also receive
notification about any source string comments made in Weblate.
Locked
You can lock the translation to prevent updates by users.
Allow translation propagation
You can disable propagation of translations to this subproject from other
subprojects within same project. This really depends on what you are
translating, sometimes it's desirable to have same string used.
Pre commit script
One of scripts defined in :setting:`PRE_COMMIT_SCRIPTS` which is executed
before commit.
Extra commit file
Additional file to include in commit, usually this one is generated by pre
commit script described above.
Save translation history
Whether to store history of translation changes in database.
Suggestion voting
Enable voting for suggestions, see :ref:`voting`.
Autoaccept suggestions
Automatically accept voted suggestions, see :ref:`voting`.
Quality checks flags
Additional flags to pass to quality checks, see :ref:`custom-checks`.
.. seealso:: :ref:`faq-vcs`, :ref:`processing`
.. _import-speed:
Importing speed
---------------
Fetching Git repository and importing translations to Weblate can be lengthy
process depending on size of your translations. Here are some tips to improve
this situation:
Clone Git repository in advance
+++++++++++++++++++++++++++++++
You can put in place Git repository which will be used by Weblate. The
repositories are stored in path defined by :setting:`GIT_ROOT` in
:file:`settings.py` in :file:`<project>/<subproject>` directories.
This can be especially useful if you already have local clone of this
repository and you can use ``--reference`` option while cloning:
.. code-block:: sh
git clone \
--reference /path/to/checkout \
git://github.com/nijel/weblate.git \
weblate/repos/project/subproject
Optimize configuration
++++++++++++++++++++++
The default configuration is useful for testing and debugging Weblate, while
for production setup, you should do some adjustments. Many of them have quite
big impact on performance. Please check :ref:`production` for more details,
especially:
* :ref:`production-indexing`
* :ref:`production-cache`
* :ref:`production-database`
* :ref:`production-debug`
Disable not needed checks
+++++++++++++++++++++++++
Some quality checks can be quite expensive and if you don't need them, they
can save you some time during import. See :setting:`CHECK_LIST` for more
information how to configure this.
.. _autocreate:
Automatic creation of subprojects
---------------------------------
In case you have project with dozen of po files, you might want to import all
at once. This can be achieved using :djadmin:`import_project`.
First you need to create project which will contain all subprojects and then
it's just a matter of running :djadmin:`import_project`.
.. seealso:: :ref:`manage`
.. _private:
Accessing private repositories
------------------------------
In case you want Weblate to access private repository it needs to get to it
somehow. Most frequently used method here is based on SSH. To have access to
such repository, you generate SSH key for Weblate and authorize it to access
the repository.
You also need to verify SSH host keys of servers you are going to access.
You can generate or display key currently used by Weblate in the admin
interface (follow :guilabel:`SSH keys` link on main admin page).
.. note::
The keys need to be without password to make it work, so be sure they are
well protected against malicious usage.
Updating repositories Updating repositories
--------------------- ---------------------
......
docs/admin/index.rst
View file @ 6e02cf49
...@@ -7,6 +7,7 @@ Administrators guide ...@@ -7,6 +7,7 @@ Administrators guide
install install
upgrade upgrade
auth auth
projects
checks checks
machine machine
admin admin
......
docs/admin/projects.rst 0 → 100644
View file @ 6e02cf49
Translation projects
====================
Translation organization
------------------------
Weblate organizes translatable content into tree like structure. The toplevel
object is :ref:`project`, which should hold all translations which belong
together (for example translation of an application in several versions
and/or documentation). On the next level, there is :ref:`subproject`, which is
actually the resource to translate. Here you define Git repository to use and
mask of files to translate. Bellow :ref:`subproject` there are individual
translations, which are handled automatically by Weblate as the translation
files (matching mask defined in :ref:`subproject`) appear in Git repository.
Adding new resources
--------------------
All translation resources need to be available as Git repositories and are
organized as project/subproject structure.
Weblate supports wide range of translation formats supported by translate
toolkit, see :ref:`formats` for more information.
.. _monolingual:
Monolingual resources
+++++++++++++++++++++
Weblate does support both multilingual and monolingual formats. For easier
translating of monolingual formats, you should provide template file, which
contains mapping of message IDs to source language (usually English).
.. _project:
Project
-------
To add new resource to translate, you need to create translation project first.
The project is sort of shelf, in which real translations are folded. All
subprojects in same project share suggestions and dictionary, also the
translations are automatically propagated through the all subproject in single
project (unless disabled in subproject configuration).
The project has only few attributes giving translators information about
project.
Commit message
++++++++++++++
The commit message on each commit Weblate does, it can use following format
strings in the message:
``%(language)s``
Language code
``%(language_name)s``
Language name
``%(subproject)s``
Subproject name
``%(project)s``
Project name
``%(total)s``
Total strings count
``%(fuzzy)s``
Fuzzy strings count
``%(fuzzy_percent)s``
Fuzzy strings percent
``%(translated)s``
Translated strings count
``%(translated_percent)s``
Translated strings percent
Adjusting interaction
+++++++++++++++++++++
There are also additional features which you can control, like automatic
pushing of changes (see also :ref:`push-changes`), merge or rebase
(see :ref:`merge-rebase`), git committer name or
maintaining of Translation-Team header.
.. _subproject:
Subproject
----------
Subproject is real resource for translating. You enter Git repository location
and file mask which files to translate and Weblate automatically fetches the Git
and finds all matching translatable files.
Should the language definition for translation be missing, empty definition is
created and named as "cs_CZ (generated)". You should adjust the definition and
report this back to Weblate authors so that missing language can be included in
next release.
The subproject contains all important parameters for working with Git and
getting translations out of it:
Repo
Git repository used to pull changes.
This can be either real Git URL or ``weblate://project/subproject``
indicating that Git repository should be shared with another subproject.
Push
Git URL used for pushing, this is completely optional and push support will
be disabled when this is empty.
Repoweb
URL of repository browser to display source files (location where messages
are used). When empty no such links will be generated.
For example on GitHub, you would use something like ``https://github.com/nijel/weblate-hello/blob/%(branch)s/%(file)s#L%(line)s``.
Branch
Which branch to checkout from the Git and where to look for translations.
Filemask
Mask of files to translate including path. It should include one *
replacing language code. In case your Git repository contains more than one
translation files (eg. more Gettext domains), you need to create separate
subproject for each. For example ``po/*.po`` or
``locale/*/LC_MESSAGES/django.po``.
Monolingual base language file
Base file containing strings definition for :ref:`monolingual`.
Base file for new translations
Base file used to generate new translations, eg. ``.pot`` file with Gettext.
Report source bugs
Email address used for reporting upstream bugs. This address will also receive
notification about any source string comments made in Weblate.
Locked
You can lock the translation to prevent updates by users.
Allow translation propagation
You can disable propagation of translations to this subproject from other
subprojects within same project. This really depends on what you are
translating, sometimes it's desirable to have same string used.
Pre commit script
One of scripts defined in :setting:`PRE_COMMIT_SCRIPTS` which is executed
before commit.
Extra commit file
Additional file to include in commit, usually this one is generated by pre
commit script described above.
Save translation history
Whether to store history of translation changes in database.
Suggestion voting
Enable voting for suggestions, see :ref:`voting`.
Autoaccept suggestions
Automatically accept voted suggestions, see :ref:`voting`.
Quality checks flags
Additional flags to pass to quality checks, see :ref:`custom-checks`.
.. seealso:: :ref:`faq-vcs`, :ref:`processing`
.. _import-speed:
Importing speed
---------------
Fetching Git repository and importing translations to Weblate can be lengthy
process depending on size of your translations. Here are some tips to improve
this situation:
Clone Git repository in advance
+++++++++++++++++++++++++++++++
You can put in place Git repository which will be used by Weblate. The
repositories are stored in path defined by :setting:`GIT_ROOT` in
:file:`settings.py` in :file:`<project>/<subproject>` directories.
This can be especially useful if you already have local clone of this
repository and you can use ``--reference`` option while cloning:
.. code-block:: sh
git clone \
--reference /path/to/checkout \
git://github.com/nijel/weblate.git \
weblate/repos/project/subproject
Optimize configuration
++++++++++++++++++++++
The default configuration is useful for testing and debugging Weblate, while
for production setup, you should do some adjustments. Many of them have quite
big impact on performance. Please check :ref:`production` for more details,
especially:
* :ref:`production-indexing`
* :ref:`production-cache`
* :ref:`production-database`
* :ref:`production-debug`
Disable not needed checks
+++++++++++++++++++++++++
Some quality checks can be quite expensive and if you don't need them, they
can save you some time during import. See :setting:`CHECK_LIST` for more
information how to configure this.
.. _autocreate:
Automatic creation of subprojects
---------------------------------
In case you have project with dozen of po files, you might want to import all
at once. This can be achieved using :djadmin:`import_project`.
First you need to create project which will contain all subprojects and then
it's just a matter of running :djadmin:`import_project`.
.. seealso:: :ref:`manage`
.. _private:
Accessing private repositories
------------------------------
In case you want Weblate to access private repository it needs to get to it
somehow. Most frequently used method here is based on SSH. To have access to
such repository, you generate SSH key for Weblate and authorize it to access
the repository.
You also need to verify SSH host keys of servers you are going to access.
You can generate or display key currently used by Weblate in the admin
interface (follow :guilabel:`SSH keys` link on main admin page).
.. note::
The keys need to be without password to make it work, so be sure they are
well protected against malicious usage.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7