Niels Thykier:
HiI am asking for English review of some strings in `debputy` with the intend to submit them for translation afterwards. I tried to send this email out in the past, but it was silently dropped by the list. This time, I am no longer including the texts themselves in my opening email to avoid being filtered on size limits.I have provided a README with the context of the strings, how they are used, etc. at https://salsa.debian.org/debian/debputy/-/blob/main/po/ debputy-lsp-data/README-translators.md?ref_type=heads. Since I expect that every translator will want to read it, it would be helpful if that was reviewed as well. If nothing else, it is still useful for understanding the scope and usage of the strings.The actual strings are compiled into https://salsa.debian.org/debian/ debputy/-/blob/main/po/debputy-lsp-data/messages.pot?ref_type=heads. The POT file is generated from YAML files; let me know if you prefer reviewing those instead of the POT file.I will try to attach both documents in a follow up email once I see this reached the list.Best regards, Niels
Hi, Here is the follow up with the messages and the README.Let me know if you prefer the YAML files to the `messages.pot` and I will send those.
Best regards, Niels
Attachment:
messages.pot
Description: MS-Powerpoint presentation
# Translatable strings for `debputy`'s LSP module
Thanks for contributing to the `debputy` LSP module. :)
This document is here to help you with some context of what you are working with.
# Target audience of the strings
The target audience of these strings are people, who work on Debian packages, of any experience
level. All strings are very technical by nature but at the same time should also be understandable
for someone very new to the packaging concepts.
This is a difficult balance to strike both for the project to provide the initial strings, but
it may also provide difficult for you as a translator. If it ever comes to prioritization between
a newcomer and a seasoned packager, the text and its translation should prioritize the newcomer
first.
The project written and maintained by seasoned packagers, which is a likely weak point in the
strings that the project provides on average.
# Scope of the strings and how they are used
The strings in this GNU gettext domain cover known fields and, where possible, known values of those fields.
The strings covers `debian/control`, `debian/copyright` (DEP-5) format and `debian/tests/control` at this
time.
The strings are handed over to an editor for exact rendering. As a consequence, they are subject to
the "do not make assumptions about exact presentation and rendering" rule that debconf templates are
subject too. Every editor can render these slightly different.
There are two major types of strings:
* [Synopsis](#synopsis)
* [Hover Doc (`long-description`)](#hover-docs-long-description)
When and how they are used will be covered in their respective subsections.
## Synopsis
The `synopsis` is used with "completion" actions. That is, if
the editor is showing the user "here are the options for what you
can insert here". The following screenshot provides an example:
The `synopsis` is a one-line plain-text string. It will be rendered
in association with the value / field name it relates to. In this
and many other ways, it works a lot like the Synopsis of a Debian
package (like having to squeeze the most out of very limited text).
The protocol used has support for marking completions as obsolete,
where the editor has a way of showing this to the user (
strike-through is a common pattern). Therefore, this should never
be specified in the text itself as there is a code level flag for
that *if* there is anything better to say in the synopsis.
That said, there are a couple of cases where we do not know what
the field did. An "anti-example" being `XS-Ruby-Versions` which has
`Obsolete (unknown usage)` as the synopsis in the lack of something
better. Here, using "Obsolete" in the synopsis was an acceptable
trade-off compared to hunting down what the obsolete field did.
A few case still use `**Advanced field**` (etc.) in their synopsis
to steer newcomers away from those or warn them about it being
potential time-sinks. The plan is to extract those into a general
marker that is included in the synopsis as a prefix. This has
already been done with "rare (but not obsolete)" fields/values.
Known TODO:
* Some "prefixes" should be turned into markers.
* The markers themselves are currently not translatable.
## Hover docs (`long-description`)
The Hover docs (called `long-description` in the source file) are
used with the LSP `Hover` requests. These are used when the user
requests more information from the editor about what they see.
The request is named `Hover` request, because usually this is
done by hovering the cursor over the subject of interest. The
following screenshot provides an example:
The strings here are markdown formatted strings that can span
multiple lines. The `debputy` side also auto-generates a header
with field name and, for values, the value. This header is
therefore omitted from the strings themselves. The header concrete
is one of:
* For field names
```markdown
# `{FIELD_NAME}`
```
* For field values:
```markdown
# `{VALUE}` (Field: `{FIELD_NAME}`)
```
The editor is expected to provide some way of scrolling the text if
it is too long. Though, it may provide a fixed size preview first,
where the user has to explicitly request the full description to
get the scrolling. Often by clicking on the preview, though exceptions
to this occur (In `emacs`, the user would run `M-X eldoc-doc-buffer`)
The editor does not inform the `debputy` program whether a fixed
size preview or the full text is rendered. It is the same request
(and the same string) for both cases and often done in a single
request. Nevertheless, it does mean that it can be worth squeezing
the most juice out of the first few lines as it can sometimes
enable the user to move on faster.
There is no rule for how large such a fixed preview is or how many
lines it spans. It depends on the editor, the font and window
size the editor is subject to at the time, etc. Therefore, there
is no hard limit on what is considered "the first few lines".
Note that `debputy` does not provide its own Markdown-to-text
module. If the editor does not support Markdown, the raw Markdown
is returned as the hover doc tagged as "plaintext" documentation.
This means the raw markdown must be able to stand alone without
being confusing to the reader.
Known TODO:
* The headers themselves are currently not translatable.
# Testing / Validating the strings
Currently, the best way to test the strings is to use the `debputy`
LSP module in your editor and try out how it works in practice.
This is a bit involved and requires that your have a text editor that supports LSP
(see <https://microsoft.github.io/language-server-protocol/implementors/tools/>
for a list of editors that is known to support this). The guide below
assumes you are working in a git checkout of the `debputy` source code.
If you are interested in this, please run:
./debputy.sh lsp features
Which will tell you if you are missing any packages for the LSP
module to run. On success, you should see `minimum requirements: enabled`
under a `General features:` header.
From there, you need to add the relevant editor configuration glue using
`./debputy.sh lsp server` or `/path/to/debputy.sh lsp server` and use your
editor on a relevant file from there. The use of `debputy.sh` is to ensure
you are using
# Improving the generated POT file itself
If you find yourself wanting to improve the POT itself, then please
review the [update_lsp_data_pots.py](../../devutils/update_lsp_data_pots.py)
script.
Attachment:
lsp-hover-doc.png
Description: PNG image
Attachment:
lsp-synopsis-completion.png
Description: PNG image
