WikiPages рекомендации по переводу страниц

From FreeCAD Documentation
Revision as of 21:35, 14 February 2022 by FuzzyBot (talk | contribs) (Updating to match new version of source page)

This page is an extension of the Help:Editing page and gives common guidelines for writing and updating the FreeCAD wiki documentation. It summarizes several discussions and brainstorming sessions

Прежде чем начать

  • Эта вики - документация основана на MediaWiki, это программное обеспечение, абсолютно аналогичное Википедии. Если вы до этого вносили правки в Википедию, то редактирование вики-страниц FreeCAD для вас должно быть легкой задачей.
  • В отличие от Википедии, вики FreeCAD защищена от записи, чтобы избежать спама. Вы должны запросить учетную запись на форуме.
  • Если вы никогда раньше не использовали программное обеспечение wiki, пожалуйста, прочитайте Help:Editing, чтобы ознакомиться с используемой разметкой.
  • Для расширенного использования программного обеспечения wiki см. MediaWiki Справка:Содержание. Не все функции MediaWiki доступны в этой вики FreeCAD, но многие из них доступны.
  • Нам нравится, чтобы документация была легкой для чтения, поэтому избегайте использования сложных функций. Пусть все будет просто.
  • Используйте песочницу для тестирования кода, например, FreeCADDocu:Sandbox или конкретную страницу с вашим именем Sandbox:Yourname.
  • Пожалуйста, обратите внимание на переводы. Вики FreeCAD использует поддержку автоматического перевода для предоставления страниц на многих языках. Для каждой страницы может существовать несколько языковых версий. На многих страницах вы увидите теги, такие как <translate>...</translate> и множество отдельных тегов, таких как <!--T:8-->. Последние создаются системой перевода. Они связывают заголовки и абзацы со своими переведенными версиями. Вы не должны изменять их, так как это разрушит эти ссылки. Однако можно перемещать абзацы или изменять формулировки до тех пор, пока теги остаются с ними. Если вы удаляете заголовок или абзац, вы также должны удалить принадлежащий ему тег. Пожалуйста, имейте в виду, что изменения в существующих заголовках и абзацах влияют на текущие переводы. Ваши изменения должны быть действительно важны, чтобы этого стоить. Не беспокойтесь при добавлении нового материала, потому что система автоматически добавит новые теги после ваших изменений. Для получения дополнительной информации см. Локализация и оригинал Mediawiki:Пример страницы для перевода.

Общие рекомендации

Краткие описания

При описании FreeCAD старайтесь быть краткими, избегать повторений и излагать свои мысли по существу. Опишите, то что FreeCAD "может сделать", а не то, что он "не может". Также избегайте разговорных выражений, таких напримаер как "пара","около того","вроде". Когда имеете дело с неопределенным числом, пишите "некоторое значение" или укажите корректное количество.

Пример плохого описания
Верстак PartDesign: верстак PartDesign, это верстак для проектирования деталей который предоставляет инструменты для моделирования сложных твердых деталей.
Пример хорошего описания
Верстак PartDesign: предоставляет инструменты для проектирования сложных твердых тел.

Централизованная информация

Избегайте дублирования одной и той же информации в разных местах. Вставьте информацию на новую страницу и добавьте ссылку на эту страницу с других страниц, которым требуется эта информация.

Do not use transclusion of pages (Help:Editing#Templates and transcluding pages), as this makes the wiki difficult to translate. Use only the templates described below in #Templates.

Стиллизирование

Templates are used to style the help pages. They give the documentation a consistent look and feel. There is a template for menu commands, File → Save, a template to style keys to be pressed, Shift, to show a Boolean value, true, etc. Please get familiar with the #Templates section before writing help pages.

Temporary flags

If you are working on a large page it is advisable to mark the page either as a work in progress or as unfinished. This assures that wiki admins don't mark your page as ready for translation while you are still changing it.

To flag a page add either {{Page in progress}} or {{UnfinishedDocu}} as the first line. With {{UnfinishedDocu}} you invite others to join you in finishing the page, while {{Page in progress}} indicates that you will do the work yourself and others should give you some time.

Once the work is done, please don't forget to remove the flags!

Примеры

To quickly get familiar with the structure and style of the FreeCAD wiki look at the model page: GuiCommand model.

Structure

The User hub provides a Table of Contents. This is used as the main reference for automatically building the offline help you can reach from FreeCAD, as well as the offline PDF documentation.

The Template:Docnav is used to sequentially link pages, following the structure of the Table of Contents. See #Templates for a list of all templates.

Названия Страниц

Page names should be short and they should use title case: every word should begin with a capital letter, unless they are articles, prepositions, conjunctions, or other grammatical particles (f.e. 'of', 'on', 'in', 'a', 'an', 'and').

Плохое название для страницы
Конструкция Аэропланов AeroCompany
Хорошее название
Конструкция аэропланов AeroCompany

The names of top level workbench pages must have this format: XYZ Workbench, where XYZ is the name of the workbench, for example PartDesign Workbench. And the names of pages describing the commands (or tools) belonging to a workbench must have this format: XYZ Command, for example PartDesign Pad. Note that you should use the command name as it occurs in the source code.

Заголовки

Paragraph headings should be short and use sentence case: all words except the first one and proper names, should be in lowercase. You should not use H1 headings (= Heading =) in your wiki markup since the page title is automatically added as the main H1 heading.

Ссылки

Вы должны использовать оригинальное название ссылки, если это возможно. Это уточняет страницу, на которую ссылается печатная или offline документация. Пожалуйста, избегайте бессмысленных слов для ссылки.

Плохая ссылка
Для получения более подробной информации по рисованию 2D объектов кликните тута.
Хорошая ссылка
Для получения более подробной информации о рисовании 2D обратитесь к верстаку Draft.

Предпочтительным форматом для ссылки является:

[[Name_of_page|name of page]]

После перевода:

[[Name_of_page/ru|название страницы]]

Note that for the part before the | character, the actual link, case is relevant. If your page name is Name_of_page the link will fail if you type Name_of_Page (upper case P). Before the | character all spaces should be replaced by underscores (_). This is to assist translators using translation software, without the underscores the link would be translated by the software which is undesirable.

To link to a certain paragraph add a # sign and its headings to the page name. Example:

[[WikiPages#Links|WikiPages]]

После перевода:

[[WikiPages/fr#Liens|WikiPages]]

Within the same page you can omit the page name. Example:

[[#Links|Links]]

To link to the top of the page you can use:

</translate>{{Top}}<translate>

This template should automatically display the correct text depending on the language of the page. A link to the top of the page is especially useful for long pages as it allows the user to quickly jump back to the table of content. You can put it at the end of each paragraph. Make sure there is an empty line before and after the template.

Image link
Optional text that is shown when you hover the image

To use an image as a link:

[[Image:Draft_Wire.svg|24px|Optional text that is shown when you hover the image|link=Draft_Wire]]

Image link + text link
Draft Wire

If you leave out the optional text the link itself will be shown when the image is hovered, which is preferable, and you should also add a text link after the image link:

[[Image:Draft_Wire.svg|24px|link=Draft_Wire]] [[Draft_Wire|Draft Wire]]

Страницы верстаков

A top level workbench page should start with:

  • A description of what the workbench is used for.
  • An image to illustrate the description.

See #Screen capture for conventions on including images.

Command pages

Command pages describing workbench tools should not be too long, they should only explain what a command can do and what it can't, and how to use it. You should keep pictures and examples to a minimum. Tutorials can expand on how to use the tool and provide step-by-step details.

Please refer to the GuiCommand model page for more details.

Руководства

A well written tutorial should teach how to achieve certain practical results quickly. It shouldn't be too long, but should include sufficient step-by-step instructions and images to guide the user. As FreeCAD evolves, tutorials may become obsolete, so it is important to mention the FreeCAD version used in, or required for, a tutorial.

For examples visit the Tutorials page.

Шаблоны

Styling of the FreeCAD wiki pages is achieved through the use of templates (Help:Editing#Templates_and_transcluding_pages). They ensure a standardized look and feel across all pages, and also make it possible to re-style the wiki. You can see the complete list of defined templates by accessing Special:PrefixIndex/Template:. But please only use the templates listed in the tables below. Only in very special cases should you use HTML tags directly.

Click on the template link to see the usage instructions for a template, and to see its implementation. Templates are a powerful feature of the MediaWiki software. You should be an experienced wiki user if you wish to propose additions and modifications to existing templates. If implemented incorrectly, templates make it difficult to translate pages into other languages, so their use should be limited to text formatting, page transclusion should be avoided. See MediaWiki Help:Templates to learn more.

Простейшие шаблоны

Эти шаблоны форматируют простой текстовый параметр в определенном стиле.

Шаблон Внешний вид Описание
Top

наверх

Use it to add a link to the top of the page.
Emphasis emphasis Используйте его, чтобы подчеркнуть фрагмент текста.
KEY Alt Используйте его в случае, когда нужно указать клавишу клавиатуры, которую необходимо нажать.
ASCII Используйте его, для отображения клавиши в виде (.svg) изображения, которую нужно нажать. В качестве параметра, вы должны указать желаемый символ или номер ascii-кода символа.
Button Cancel Используйте его для указания кнопки в графическом пользовательском интерфейсе, которую необходимо нажать.
RadioButton Option Use it to indicate a radio button in the graphical user interface that needs to be Selected or Not.
CheckBox Option Use it to indicate a checkbox in the graphical user interface that needs to be Checked or Not.
SpinBox 1.50 Use it to indicate a spinbox in the graphical user interface that needs to be modified.
ComboBox Menu 1 Use it to indicate a combobox in the graphical user interface that needs to be modified.
FALSE, false false, false Use it to indicate a False Boolean value, for example, as a property in the property editor. This is a shortcut. Since it is a value, prefer Template Value false
TRUE, true true, true Use it to indicate a True Boolean value, for example, as a property in the property editor. This is a shortcut. Since it is a value, prefer Template Value true
MenuCommand File → Save Use it to indicate the location of a command inside a particular menu.
FileName File name Используйте его для указания имени файла или каталога.
SystemInput Type this text Use it to indicate user typed input text.
SystemOutput Output text Use it to indicate text output from the system.
Incode import FreeCAD Используйте его для выделения блоков исходного кода написанного моноширинным шрифтом. Содержимое должно умещаться в одну строку.
PropertyView ВидColor Use it to indicate a View property in the property editor. Examples of View properties include Line Color, Line Width, Point Color, Point Size, etc.
PropertyData ДанныеPosition Use it to indicate a Data property in the property editor. Data properties are different for different types of objects.
Properties Title / TitleProperty Base Use it to indicate the title of a property group in the property editor. The title will not be included in the automatic table of contents.
Obsolete obsolete in version 0.19 Используйте его, чтобы указать, что функция устарела в указанной версии FreeCAD.
Version/ru представлено в версии 0.18 Используйте его, чтобы указать, что функция была введена в указанной версии FreeCAD.
VersionMinus version 0.16 and below Use it to indicate that a feature is available in the specified FreeCAD version and earlier versions.
VersionPlus version 0.17 and above Use it to indicate that a feature is available in the specified FreeCAD version and later versions.
ColoredText Colored Text Use this template to color the background, text, or background and text. (ColoredText page for more examples)
ColoredParagraph
Colored Paragraph
Use this template to color the background, text, or background and text of an entire paragraph. ColoredParagraph page for more examples)

Сборные шаблоны

These templates require more input parameters, or produce a block of text with a particular format.

Template Appearance Description
Prettytable This table Use it to format tables such as this one. Additional table properties can be added.
Caption

Some caption for an image

Use it to add an explanation below an image. It can be left aligned or center aligned.
Clear Use it to clear columns. Follow the definition of the template for a detailed explanation. It is often used to stop text from flowing next to unrelated images.
Code
import FreeCAD
Use it to include multi-line code examples with a monospace font. The default language is Python, but other languages can be specified.

Python code should adhere to the general recommendations established by PEP8: Style Guide for Python Code. In particular, parentheses should immediately follow the function name, and a space should follow a comma. This makes the code more readable

Fake heading
Heading
Use it to create a heading that will not be automatically included in the table of contents.
GuiCommand See GuiCommand model Use it to create a box with useful information to document workbench commands (tools).
TutorialInfo See for example Basic modeling tutorial Use it to create a box with useful information to document tutorials.
Macro See for example Macro FlattenWire Use it to create a box with useful information to document macros.
Docnav
Online Help Startpage
Feature list
Use it to create a bar with the words 'next', 'previous', and 'index', and the appropriate links, which is useful for putting pages in a particular sequence.
VeryImportantMessage
Important Message
Use it to create a highlighted box with a very important message. Use sparingly, only to indicate major problems in the functionality of the software, discontinuation of tools, and similar.
Page in progress
This documentation is a work in progress. Please don't mark it as translatable since it will change in the next hours and days.
Use this for pages that are still in progress or that are currently being reworked. Don't forget to remove this when the page is ready.
UnfinishedDocu

This documentation is not finished. Please help and contribute documentation.

GuiCommand model explains how commands should be documented. Browse Category:UnfinishedDocu to see more incomplete pages like this one. See Category:Command Reference for all commands.

See WikiPages to learn about editing the wiki pages, and go to Help FreeCAD to learn about other ways in which you can contribute.

Use it to create a highlighted box indicating an unfinished documentation page.
Softredirect Use it instead of the normal redirect, when you are redirecting to a special page (such as Media: or Category:), in which cases the normal redirect is disabled.
Quote

Cry "Havoc" and let slip the dogs of war.

—William Shakespeare, Julius Caesar, act III, scene I
Use it to create a box of text with a literal quote and reference.
Userdocnavi, Powerdocnavi Use them to create navigation boxes for the user documentation, the power user documentation, and the developer documentation. This allows quickly jumping between different sections of the documentation. They also place the corresponding page in the proper category.

Графика

Изображения и скриншоты необходимы для создания полной документации FreeCAD. Они особенно полезны для иллюстрации примеров и учебных пособий. Изображения должны быть показаны в их оригинальном размере, чтобы они представляли достаточную детализацию и были читабельны, если они содержат в себе текст. Размеры растровых изображений не могут быть изменены.

Избегайте анимированных картинок (GIF) на страницах общей справки. Анимации и видео следует зарезервировать для учебных пособий, не предназначенных для использования в качестве offline документации в формате PDF.

Изображения можно загрузить через Special:Upload страницу.

Name

Give meaningful names to your images. If you have an image that showcases the characteristics of a particular command, you should use the name of that command with _example at the end. For example for the command Draft Offset the image should be called Draft_Offset_example.png.

Снимки с экрана

Рекомендуемые размеры для снимков экрана::

  • 400x200 (или ширина=400 и высота<=200) для страниц описывающих команнды Gui, чтобы изображение помещалось в левой части страницы, а также для других стандартных снимков.
  • 600x400 (или ширина=600 и высота<=400), для страниц описывающих команнды Gui, только когда вам действительно нужно изображение большего размера, и при этом старйтесь уместить изображение в левой части страницы, а также для других стандартных снимков.
  • 1024x768 (или ширина=1024 и высота<=768), только для полноэкранных изображений.
  • При отображении деталей возможны меньшие размеры.
  • Избегайте изображений с большим разрешением, так как они не будут очень переносимыми для других видов дисплеев или печатной документации в формате PDF.

Вы не должны зависеть от пользовательской конфигурации вашего рабочего стола или операционной системы при создании скриншотов, по возможности рекомендуется использовать визуальные настройки интерфейса FreeCAD по умолчанию.

To create a screenshots you can use the options provided by your operating system, or one of these macros: Macro Snip and Macro Screen Wiki.

Text

To ease documentation translations, try to avoid screenshots that contain texts. If you cannot avoid this, consider taking separate screenshots of the interface and the 3D view. The image of the 3D view can be reused in every translation, while a translator can take a screenshot of the localized interface if necessary.

Иконки и графика

Refer to the Artwork page for all artwork and icons that have been created for FreeCAD, and which can also be used in documentation pages. If you would like to contribute icons, please read the Artwork Guidelines.

Переводы

As per general consensus, the reference page in the wiki is the English page, which should be created first. If you want to change or add content to a page, you should do it to the English page first, and only once the update is completed, port the modification to the translated page.

The FreeCAD wiki supports a translation extension that allows managing translations between pages easier; for details, see Localisation Translating the wiki.

Other useful resources are:

Несколько советов для переводчиков

Translate GuiCommand

{{GuiCommand
|Name=FEM EquationFlux
|MenuLocation=Solve → Flux equation
|Workbenches=[[FEM_Workbench|FEM]]
|Shortcut={{KEY|F}} {{KEY|S}}
|Version=0.17
|SeeAlso=[[FEM_tutorial|FEM tutorial]]
}}

Translated:

{{GuiCommand/fr
|Name=FEM EquationFlux
|Name/fr=FEM Équation d'écoulement
|MenuLocation=Solveur → Équation de flux
|Workbenches=[[FEM_Workbench/fr|Atelier FEM]]
|Shortcut={{KEY|F}} {{KEY|S}}
|Version=0.17
|SeeAlso=[[FEM_tutorial/fr|FEM Tutoriel]]
}}

Translate navi

{{FEM_Tools_navi}}

Translated:

{{FEM_Tools_navi/fr}}

Translate link

[[Part_Module|Part Module]]

Translated:

[[Part_Module/fr|Atelier Part]]

Translate Docnav

{{Docnav
|[[About_FreeCAD|About FreeCAD]]
|[[Installing_on_Windows|Installing on Windows]]
}}

Translated:

{{Docnav/fr
|[[About_FreeCAD/fr|À propos de FreeCAD]]
|[[Installing_on_Windows/fr|Installation sous Windows]]
}}

Example with icons:

{{Docnav
|[[Std_Save|Save]]
|[[Std_SaveCopy|SaveCopy]]
|[[Std_File_Menu|Std File Menu]]
|IconL=Std_Save.svg
|IconR=Std_SaveCopy.svg
|IconC=Freecad.svg
}}

Translated:

{{Docnav/fr
|[[Std_Save/fr|Enregistrer]]
|[[Std_SaveCopy/fr|Enregistrer une copie]]
|[[Std_File_Menu/fr|Menu fichier]]
|IconL=Std_Save.svg
|IconR=Std_SaveCopy.svg
|IconC=Freecad.svg
}}

Создание, переименовывание и удаление страниц

Create pages

Before creating a new page you should first check if a similar page already exists. If that is the case it is usually better to edit that existing page instead. When in doubt please open a topic in the Wiki forum first.

To create a new page do one of the following:

  • Visit the URL with the desired page name, for example: https://wiki.freecadweb.org/My_new_page, and click on 'create this page'.
  • Do a wiki search for the page name, and click on the red text in 'Create the page "My new page" on this wiki!'.

Rename pages

Since FreeCAD is a project under permanent development, it is sometimes necessary to revise the content of the wiki. If the names of commands are changed in the source code, the wiki pages documenting them have to be renamed as well. This can only be done by wiki administrators. To inform them, open a topic in the Wiki forum and list the necessary renaming operation in this form:

old name         new name
Old_page_name_1  New_page_name_1
Old_page_name_2  New_page_name_2
...

Удаление файлов и страниц

В случае, если вам нужно удалить файл, перейдите на его страницу (https://www.freecadweb.org/wiki/File:***.***) и отредактируйте его. Независимо от того, является ли страница пустой или нет, добавьте это в качестве первого элемента: {{Delete}} и прямо под ним опишите, почему страница должна быть удалена. Помимо этого, откройте тему в Вики-форуме.

Для страниц процедура идентичная.

Обсуждение

The Development/Wiki subforum in the FreeCAD forum provides a dedicated space for discussing wiki topics, the wiki appearance and anything else related to the wiki. Direct your questions and suggestions there.

Терминология - стратегия именования

На английском

Смотри Глоссарий.

Другие языки