godotengine/godot-docs-l10n
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs-l10n.git synced 2025-12-31 09:49:22 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
c9fa49933cb381a9946ccd19a4f084619de4504b
godot-docs-l10n/sphinx/templates/community/contributing/docs_writing_guidelines.pot
Rémi Verschelde c9fa49933c Sync Sphinx and Weblate templates with current docs
2022-09-09 16:05:06 +02:00

500 lines
22 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2014-2022, Juan Linietsky, Ariel Manzur and the Godot community (CC-BY 3.0)
# This file is distributed under the same license as the Godot Engine package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Godot Engine 3.5\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2022-09-09 16:03+0200\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#: ../../docs/community/contributing/docs_writing_guidelines.rst:4
msgid "Docs writing guidelines"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:6
msgid "The Godot community is rich and international. Users come from all around the world. Some of them are young, and many aren't native English speakers. That's why we must all write using a clear and a common language. For the class reference, the goal is to make it easy to read for everyone and precise."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:12
msgid "In summary, always try to:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:14
#: ../../docs/community/contributing/docs_writing_guidelines.rst:44
msgid "Use the active voice"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:15
#: ../../docs/community/contributing/docs_writing_guidelines.rst:79
msgid "Use precise action verbs"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:16
#: ../../docs/community/contributing/docs_writing_guidelines.rst:101
msgid "Avoid verbs that end in -ing"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:17
msgid "Remove unnecessary adverbs and adjectives."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:18
msgid "Ban these 8 words: obvious, simple, basic, easy, actual, just, clear, and however"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:19
#: ../../docs/community/contributing/docs_writing_guidelines.rst:219
msgid "Use explicit references"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:20
#: ../../docs/community/contributing/docs_writing_guidelines.rst:240
msgid "Use 's to show possession"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:21
msgid "Use the Oxford comma"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:23
msgid "There are 3 rules to describe classes:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:25
#: ../../docs/community/contributing/docs_writing_guidelines.rst:377
msgid "Give an overview of the node in the brief description"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:26
#: ../../docs/community/contributing/docs_writing_guidelines.rst:406
msgid "Mention what methods return if it's useful"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:27
#: ../../docs/community/contributing/docs_writing_guidelines.rst:431
msgid "Use \"if true\" to describe booleans"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:31
msgid "A technical writer's job is to pack as much information as possible into the smallest and clearest sentences possible. These guidelines will help you work towards that goal."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:37
msgid "See the :ref:`content guidelines <doc_content_guidelines>` for information on the types of documentation you can write in the official documentation."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:41
msgid "7 rules for clear English"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:46
msgid "Use the active voice when possible. Take the classes, methods, and constants you describe as the subject. It's natural to write using the passive voice, but it's harder to read and produces longer sentences."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:52
msgid "Passive:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:58
msgid "Active:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:64
#: ../../docs/community/contributing/docs_writing_guidelines.rst:412
msgid "**Don't** use the passive voice:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:71
msgid "**Do** use the node's name as a noun:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:81
msgid "Favor precise yet common verbs over generic ones like ``make``, ``set``, and any expression you can replace with a single word."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:84
msgid "**Don't** repeat the method's name. It already states it sets the pivot value to a new one:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:92
msgid "**Do** explain what's the consequence of this \"set\": use precise verbs like ``place``, ``position``, ``rotate``, ``fade``, etc."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:103
msgid "The progressive forms describe continuous actions. E.g. \"is calling\", \"is moving\"."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:106
msgid "**Don't** use the progressive form for instant changes."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:113
msgid "**Do** use simple present, past, or future."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:120
msgid "Exception: If the subject is not clear, replacing \"ing\" verbs is not an improvement. For example, in the previous sentence, \"it replaces\" would not make much sense where \"replacing\" currently is."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:124
msgid "You may use the progressive tense to describe actions that are continuous in time. Anything like animation or coroutines."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:129
msgid "Verbs can turn into adjectival nouns with -ing. This is not a conjugation, so you may use them: ``the remaining movement``, ``the missing file``, etc."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:134
msgid "Remove unnecessary adverbs and adjectives"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:136
msgid "Write as few adjectives and adverbs as possible. Only use them if they add key information to the description."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:139
msgid "**Don't** use redundant or meaningless adverbs. Words that lengthen the documentation but don't add any information:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:146
msgid "**Do** write short sentences in a simple, descriptive language:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:153
msgid "Ban these 8 words"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:155
msgid "**Don't** ever use these 8 banned words:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:157
msgid "obvious"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:158
msgid "simple"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:159
msgid "basic"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:160
msgid "easy"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:161
msgid "actual"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:162
msgid "just"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:163
msgid "clear"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:164
msgid "however (some uses)"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:166
msgid "Game creation and programming aren't simple, and nothing's easy to someone learning to use the API for the first time. Other words in the list, like ``just`` or ``actual`` won't add any info to the sentence. Don't use corresponding adverbs either: obviously, simply, basically, easily, actually, clearly."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:172
msgid "**Don't** example. The banned words lengthen the description and take attention away from the most important info:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:180
msgid "**Do** remove them:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:187
msgid "\"Simple\" never helps. Remember, for other users, anything could be complex or frustrate them. There's nothing like a good old *it's simple* to make you cringe. Here's the old brief description, the first sentence on the Timer node's page:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:197
msgid "**Do** explain what the node does instead:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:204
msgid "**Don't** use \"basic\", it is too vague:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:211
msgid "**Do** use the brief description to offer an overview of the node:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:221
msgid "Favor explicit references over implicit ones."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:223
msgid "**Don't** use words like \"the former\", \"the latter\", etc. They're not the most common in English, and they require you to check the reference."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:230
msgid "**Do** repeat words. They remove all ambiguity:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:236
msgid "If you need to repeat the same variable name 3 or 4 times, you probably need to rephrase your description."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:242
msgid "Avoid \"The milk **of** the cow\". It feels unnatural in English. Write \"The cow's milk\" instead."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:245
msgid "**Don't** write \"of the X\":"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:251
msgid "**Do** use ``'s``. It lets you put the main subject at the start of the sentence, and keep it short:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:259
msgid "Use the Oxford comma to enumerate anything"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:261
msgid "From the Oxford dictionary:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:263
msgid "The 'Oxford comma' is an optional comma before the word 'and' at the end of a list: *We sell books, videos, and magazines.*"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:266
msgid "[...] Not all writers and publishers use it, but it can clarify the meaning of a sentence when the items in a list are not single words: *These items are available in black and white, red and yellow, and blue and green.*"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:269
msgid "**Don't** leave the last element of a list without a comma:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:275
msgid "**Do** add a comma before `and` or `or`, for the last element of a list with more than two elements."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:284
msgid "How to write methods and classes"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:287
msgid "Dynamic vs static typing"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:289
msgid "The code examples in the documentation should follow a consistent style not to confuse users. As static type hints are an optional feature of GDScript, we chose to stick to writing dynamic code. This leads to writing GDScript that is concise and accessible."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:294
msgid "The exception is topics that explain static typing concepts to users."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:296
msgid "**Don't** add a type hint with a colon or by casting:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:306
msgid "**Do** write constants and variables with dynamic typing:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:316
msgid "**Don't** write functions with inferred arguments or return types:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:327
msgid "**Do** write functions using dynamic typing:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:339
msgid "Use real-world code examples where appropriate"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:341
msgid "Real-world examples are more accessible to beginners than abstract ``foos`` and ``bars``. You can also copy them directly from your game projects, ensuring that any code snippet compiles without errors."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:345
msgid "Writing ``var speed = 10`` rather than ``var my_var = 10`` allows beginners to understand code better. It gives them a frame of reference as to where they could use the code snippets in a live project."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:349
msgid "**Don't** write made-up examples:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:360
msgid "**Do** write concrete examples:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:372
msgid "Of course, there are times when using real-world examples is impractical. In those situations, you should still avoid using names such as ``my_var``, ``foo()`` or ``my_func()`` and consider more meaningful names for your examples."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:379
msgid "The brief description is the reference's most important sentence. It's the user's first contact with a node:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:382
msgid "It's the only description in the \"Create New Node\" dialog."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:383
msgid "It's at the top of every page in the reference"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:385
msgid "The brief description should explain the node's role and its functionality, in up to 200 characters."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:388
msgid "**Don't** write tiny and vague summaries:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:395
msgid "**Do** give an overview of the node's functionality:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:402
msgid "Use the node's full description to provide more information, and a code example, if possible."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:408
msgid "Some methods return important values. Describe them at the end of the description, ideally on a new line. No need to mention the return values for any method whose name starts with ``set`` or ``get``."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:419
msgid "**Do** always use \"Returns\"."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:426
msgid "Notice the exception to the \"direct voice\" rule: with the move method, an external collider can influence the method and the body that calls ``move``. In this case, you can use the passive voice."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:433
msgid "For boolean member variables, always use ``if true`` and/or ``if false``, to stay explicit. ``Controls whether or not`` may be ambiguous and won't work for every member variable."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:437
msgid "Also, surround boolean values, variable names and methods with ``[code][/code]``."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:439
msgid "**Do** start with \"if true\":"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:448
msgid "Use ``[code]`` around arguments"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:450
msgid "In the class reference, always surround arguments with ``[code][/code]``. In the documentation and in Godot, it will display like ``this``. When you edit XML files in the Godot repository, replace existing arguments written like 'this' or \\`this\\` with ``[code]this[/code]``."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:457
msgid "Common vocabulary to use in Godot's documentation"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:459
msgid "The developers chose some specific words to refer to areas of the interface. They're used in the sources, in the documentation, and you should always use them instead of synonyms, so the users know what you're talking about."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:467
#: ../../docs/community/contributing/docs_writing_guidelines.rst:467
msgid "Overview of the interface and common vocabulary"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:469
msgid "In the top left corner of the editor lie the ``main menus``. In the center, the buttons change the ``workspace``. And together the buttons in the top right are the ``playtest buttons``. The area in the center, that displays the 2D or the 3D space, is the ``viewport``. At its top, you find a list of ``tools`` inside the ``toolbar``."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:475
msgid "The tabs or dockable panels on either side of the viewport are ``docks``. You have the ``FileSystem dock``, the ``Scene dock`` that contains your scene tree, the ``Import dock``, the ``Node dock``, and the ``Inspector`` or ``Inspector dock``. With the default layout you may call the tabbed docks ``tabs``: the ``Scene tab``, the ``Node tab``..."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:481
msgid "The Animation, Debugger, etc. at the bottom of the viewport are ``panels``. Together they make up the ``bottom panels``."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:484
msgid "Foldable areas of the Inspector are ``sections``. The node's parent class names, which you can't fold, are ``Classes`` e.g. the ``KinematicBody2D class``. And individual lines with key-value pairs are ``properties``. E.g. ``position`` or ``modulate color`` are both ``properties``."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:491
msgid "Keyboard shortcut guidelines"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:493
msgid "Keyboard and mouse shortcuts should make use of the ``:kbd:`` tag, which allows shortcuts to stand out from the rest of the text and inline code. Use the compact form for modifier keys (:kbd:`Ctrl`/:kbd:`Cmd`) instead of their spelled out form (:kbd:`Control`/:kbd:`Command`). For combinations, use the ``+`` symbol with a space on either side of the symbol."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:499
msgid "Make sure to mention shortcuts that differ on macOS compared to other platforms. On macOS, ``Cmd`` often replaces ``Ctrl`` in keyboard shortcuts."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:502
msgid "Try to integrate the shortcut into sentences the best you can. Here are some examples with the ``:kbd:`` tag left as-is for better visibility:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:505
msgid "Press ``:kbd:`Ctrl + Alt + T``` to toggle the panel (``:kbd:`Cmd + Alt + T``` on macOS)."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:506
msgid "Press ``:kbd:`Space``` and hold the left mouse button to pan in the 2D editor."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:507
msgid "Press ``:kbd:`Shift + Up Arrow``` to move the node upwards by 8 pixels."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:510
msgid "Image contribution guidelines"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:512
msgid "A significant part of the documentation is images, and there are several important guidelines to follow."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:515
msgid "First, you should always be using the default editor theme and text when taking screenshots."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:518
msgid "To improve the appearance of 3D screenshots, use 4× MSAA, enable anisotropic filtering on the project's textures, and set the anisotropic filter quality to 16× in Project Settings."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:522
msgid "Screenshot sizes should not exceed 1920×1080 to ensure fast loading on slower connections."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:525
msgid "When you need to highlight an area of the editor to show something, like a button or option, use a 2 pixel-thick yellow outline without a bevel. If the outline is on a dark background, the outline should be yellow so it can be easily seen by colorblind people. Please do not use red as it won't be visible for some users."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:531
msgid "Before you add or replace any images in the documentation, they should be run through a PNG compressor to save size. You can use the lossless OxiPNG compressor included in `Squoosh <https://squoosh.app/>`__ for this purpose. For heavier images, consider using a lossy compressor like `pngquant <https://pngquant.org/>`_. With it, almost no image quality is lost during compression."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:540
msgid "The program pngquant must be installed locally as it's not available in Squoosh."
msgstr ""
#: ../../docs/<rst_epilog>:0
msgid "Translation status"
msgstr ""
Reference in New Issue View Git Blame Copy Permalink