192 lines
6.7 KiB
Markdown
192 lines
6.7 KiB
Markdown
+++
|
|
title = "How to contribute"
|
|
description = "How to contribute to this intro tutorial"
|
|
chapter = false
|
|
weight = 5
|
|
+++
|
|
|
|
## What Kind Of Contributions We Accept
|
|
|
|
We intentionally limit the scope of this tutorial to very basic techniques that
|
|
are sufficient to get users started with recording, mixing, and exporting with
|
|
Ardour. So we'll gratefully accept patches that do not change the scope in any
|
|
major way: bug fixes, better explanations, better illustrations etc. We also
|
|
encourage translations of the ardour-tutorial.
|
|
|
|
## Using Markdown Syntax And Extras
|
|
|
|
All text files use Markdown syntax with a few extras. We use a limited subset of
|
|
available options and one shortcode specific to HTML5, a `<figure>` element
|
|
([see here](https://gohugo.io/content-management/shortcodes/#figure) for more
|
|
info). Another extra feature available in the template of choice is a so called
|
|
shortcode for notice boxes that look like this:
|
|
|
|
{{% notice tip %}}
|
|
Some text
|
|
{{% /notice %}}
|
|
|
|
We generally stick to two type of notice boxes: 'tip' and 'warning'.
|
|
|
|
The rest is really straightforward:
|
|
|
|
- Single underscore like `_Name_` makes italics and is used for UI elements like
|
|
window captions.
|
|
- Double asterisk like `**OK**` makes bolds and is reserved for button captions.
|
|
- Backticks around some text are typically reserved for menu paths and filenames.
|
|
|
|
## How to Submit Changes
|
|
|
|
The repository with this tutorial is available on GitHub. The general idea is
|
|
that you fork the repository, make changes in a branch, then create a pull
|
|
request. Please [see
|
|
here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
|
|
for a complete guide.
|
|
|
|
## How To Create And Submit A Translation
|
|
|
|
The entire tutorial can be translated into a different language. Once you create
|
|
a git branch to separate your work, here is what you do next.
|
|
|
|
### Translating Menu
|
|
|
|
The menu is stored in `config.toml`, inside the `[Languages]` section. For each
|
|
language, that section has two parts:
|
|
|
|
1. The main part where names of chapters and pages chow up.
|
|
2. The 'shortcuts' menu with links to Ardour's homepage, forum etc.
|
|
|
|
To translate the header of the main part, copy and paste the entire block that
|
|
starts with `[Languages.en]` and then:
|
|
|
|
1. Change the language code in `[Languages.en]`.
|
|
2. Translate the title.
|
|
3. Submit the name of the language that will show up in the drop-down list of
|
|
available translations. We encourage you to use language
|
|
or the local one, in your alphabet — whichever works for you.
|
|
4. Change the two-letter language code in the line that starts with
|
|
`landingPageURL`.
|
|
5. Translate the caption of the homepage of the tutorial in the line that starts
|
|
with `landingPageName`.
|
|
|
|
Thus
|
|
|
|
~~~
|
|
[Languages.en]
|
|
title = "Ardour tutorial"
|
|
weight = 1
|
|
languageName = "English"
|
|
landingPageURL = "/ardour-tutorial/en/"
|
|
#landingPageURL = "/"
|
|
landingPageName = "<i class='fas fa-home'></i> Home"
|
|
~~~
|
|
|
|
translates to e.g.:
|
|
|
|
~~~
|
|
[Languages.ru]
|
|
title = "Введение в Ardour"
|
|
weight = 1
|
|
languageName = "Russian"
|
|
landingPageURL = "/ardour-tutorial/ru/"
|
|
#landingPageURL = "/"
|
|
landingPageName = "<i class='fas fa-home'></i> Начало"
|
|
~~~
|
|
|
|
This main part of the menu will start automatically accumulating links to
|
|
translated pages as you start adding pages with translations.
|
|
|
|
Use the same approach to translate the shortcuts menu. E.g. the link to Ardour's
|
|
website
|
|
|
|
~~~
|
|
[[Languages.en.menu.shortcuts]]
|
|
name = "<i class='fas fa-fw fa-home'></i> Ardour's homepage"
|
|
url = "https://ardour.org/"
|
|
weight = 11
|
|
~~~
|
|
|
|
becomes
|
|
|
|
~~~
|
|
#[[Languages.ru.menu.shortcuts]]
|
|
#name = "<i class='fas fa-fw fa-home'></i> Сайт Ardour"
|
|
#url = "https://ardour.org/"
|
|
#weight = 11
|
|
~~~
|
|
|
|
Please keep all translations of the menu in a single larger block.
|
|
|
|
### Translating Chapters And Pages
|
|
|
|
All content lives inside the `content` folder where subfolders are names of
|
|
chapters like _Recording_ (`recording`), _Mixing sessions_ (`mixing-sessions`)
|
|
etc. Here is the general structure:
|
|
|
|
~~~
|
|
/content # The root folder for all content
|
|
/content/_index.en.md # The start page you see when you click Home
|
|
/content/chapter-folder/ # The folder for an entire chapter like "Recording"
|
|
/content/chapter-folder/_index.en.md # Chapter
|
|
/content/chapter-folder/page/ # Folder for a page in a chapter, e.g. "Understanding Routing"
|
|
/content/chapter-folder/page/index.md # Original text of that page in English
|
|
/content/chapter-folder/page/en/ # Screenshots created with English user interface
|
|
~~~
|
|
|
|
All text files have a language code right in the file name:
|
|
|
|
- regular pages are named `index.XX.md`,
|
|
- chapters are named `_index.XX.md`,
|
|
|
|
where XX is a two-letter language code like 'de' for German or 'fr' for French. You should be able to use four-letter codes as well, e.g. 'pt_BR' or 'es_AR'.
|
|
|
|
Supposing you want to translate the _Getting Started_ chapter into French. Here
|
|
is how you do it.
|
|
|
|
1. Create a copy of `getting-started/_index.en.md` and name it `_index.fr.md`.
|
|
Now you should have `_index.en.md` and `_index.fr.md` in the same folder.
|
|
|
|
2. Translate `_index.fr.md`. If you already translated the main menu, you should
|
|
be able to open the original page in English, switch the language to 'Français'
|
|
and see your translated page.
|
|
|
|
3. Go to the `starting-ardour` subfolder, create a copy of `index.en.md` and
|
|
name it `index.fr.md` and then translate it.
|
|
|
|
4. Repeat step 3 for all subfolders. This should give you the translation of an
|
|
entire chapter on getting started with Ardour.
|
|
|
|
### Translating User Interface Elements and Screenshots
|
|
|
|
If Ardour's user interface is available in the language you are translating this
|
|
tutorial into, it is generally up to you to decide if you refer to localized
|
|
user interface or not.
|
|
|
|
We know that users are very passionate about both localized and non-localized
|
|
UIs, so one approach you could take is to create localized screenshots, refer to
|
|
localized user interface and then mention the English counterparts in
|
|
parenthesis. Here is an example of a translation into German:
|
|
|
|
> Nach dem Import einiger Sounds aus dem heruntergeladenen Sample-Pack
|
|
(Bassdrum, Snare, Hi-Hat, Clap) sieht unsere Session so aus (in diesem Fall
|
|
haben wir die Option _Dateien als neue Spuren hinzufügen_ (EN: _Add files as new
|
|
tracks_) verwendet und beim Start der Session eingefügt.
|
|
|
|
If you intend to create screenshots of localized user interface, please create a
|
|
subfolder that's named after a language code (two-letter of four-letter,
|
|
whichever is applicable) and place your screenshots there. Having done so,
|
|
please update references to screenshots in the text. E.g.
|
|
|
|
~~~
|
|
src="en/ardour7-save-template.png"
|
|
~~~
|
|
|
|
becomes
|
|
|
|
~~~
|
|
src="de/ardour7-schablone-speichern.png"
|
|
~~~
|
|
|
|
### Submitting Translation
|
|
|
|
The process is the same as for general patches: submit a pull request. See above
|
|
for a link to a step-by-step guide. |