godotengine/godot-docs-l10n
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs-l10n.git synced 2026-01-04 10:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
b0a37ce3ecbbb9b77e8b44180d16e1e5f42b9d47
godot-docs-l10n/sphinx/templates/community/contributing/docs_writing_guidelines.pot
Rémi Verschelde b0a37ce3ec Sync Sphinx and Weblate templates with current docs
2021-11-19 11:11:47 +01:00

491 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-2021, 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.4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2021-11-19 11:09+0100\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:39
msgid "Use the direct voice"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:15
#: ../../docs/community/contributing/docs_writing_guidelines.rst:74
msgid "Use precise action verbs"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:16
#: ../../docs/community/contributing/docs_writing_guidelines.rst:96
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:214
msgid "Use explicit references"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:20
#: ../../docs/community/contributing/docs_writing_guidelines.rst:235
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:372
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:401
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:426
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:36
msgid "7 rules for clear English"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:41
msgid "Use the direct 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:47
msgid "Passive:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:53
msgid "Active:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:59
#: ../../docs/community/contributing/docs_writing_guidelines.rst:407
msgid "**Don't** use the passive voice:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:66
msgid "**Do** use the node's name as a noun:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:76
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:79
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:87
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:98
msgid "The progressive forms describe continuous actions. E.g. \"is calling\", \"is moving\"."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:101
msgid "**Don't** use the progressive form for instant changes."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:108
msgid "**Do** use simple present, preterit or future."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:115
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:119
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:124
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:129
msgid "Remove unnecessary adverbs and adjectives"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:131
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:134
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:141
msgid "**Do** write short sentences in a simple, descriptive language:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:148
msgid "Ban these 8 words"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:150
msgid "**Don't** ever use these 8 banned words:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:152
msgid "obvious"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:153
msgid "simple"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:154
msgid "basic"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:155
msgid "easy"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:156
msgid "actual"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:157
msgid "just"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:158
msgid "clear"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:159
msgid "however (some uses)"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:161
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:167
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:175
msgid "**Do** remove them:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:182
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:192
msgid "**Do** explain what the node does instead:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:199
msgid "**Don't** use \"basic\", it is too vague:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:206
msgid "**Do** use the brief description to offer an overview of the node:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:216
msgid "Favor explicit references over implicit ones."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:218
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:225
msgid "**Do** repeat words. They remove all ambiguity:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:231
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:237
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:240
msgid "**Don't** write \"of the X\":"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:246
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:254
msgid "Use the Oxford comma to enumerate anything"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:256
msgid "From the Oxford dictionary:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:258
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:261
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:264
msgid "**Don't** leave the last element of a list without a comma:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:270
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:279
msgid "How to write methods and classes"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:282
msgid "Dynamic vs static typing"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:284
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:289
msgid "The exception is topics that explain static typing concepts to users."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:291
msgid "**Don't** add a type hint with a colon or by casting:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:301
msgid "**Do** write constants and variables with dynamic typing:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:311
msgid "**Don't** write functions with inferred arguments or return types:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:322
msgid "**Do** write functions using dynamic typing:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:334
msgid "Use real-world code examples where appropriate"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:336
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:340
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:344
msgid "**Don't** write made-up examples:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:355
msgid "**Do** write concrete examples:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:367
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:374
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:377
msgid "It's the only description in the \"Create New Node\" dialog."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:378
msgid "It's at the top of every page in the reference"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:380
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:383
msgid "**Don't** write tiny and vague summaries:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:390
msgid "**Do** give an overview of the node's functionality:"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:397
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:403
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:414
msgid "**Do** always use \"Returns\"."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:421
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:428
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:432
msgid "Also, surround boolean values, variable names and methods with ``[code][/code]``."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:434
msgid "**Do** start with \"if true\":"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:443
msgid "Use ``[code]`` around arguments"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:445
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:452
msgid "Common vocabulary to use in Godot's documentation"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:454
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:462
msgid "Overview of the interface and common vocabulary"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:464
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:470
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:476
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:479
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:486
msgid "Keyboard shortcut guidelines"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:488
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:494
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:497
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:500
msgid "Press ``:kbd:`Ctrl + Alt + T``` to toggle the panel (``:kbd:`Cmd + Alt + T``` on macOS)."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:501
msgid "Press ``:kbd:`Space``` and hold the left mouse button to pan in the 2D editor."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:502
msgid "Press ``:kbd:`Shift + Up Arrow``` to move the node upwards by 8 pixels."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:505
msgid "Image contribution guidelines"
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:507
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:510
msgid "First, you should always be using the default editor theme and text when taking screenshots."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:513
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:517
msgid "Screenshot sizes should not exceed 1920×1080 to ensure fast loading on slower connections."
msgstr ""
#: ../../docs/community/contributing/docs_writing_guidelines.rst:520
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:526
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:535
msgid "The program pngquant must be installed locally as it's not available in Squoosh."
msgstr ""
Reference in New Issue View Git Blame Copy Permalink