Add a Vignette on anatomy of a description file

[cregouby]

No description provided.

[eliocamp]

Hi @cregouby, thank you for the proposal. Before merging the vignette, I think there's need to be a discussion about the suggestions given by it.

1. Matching translation module version and package version

Why do you think it would be better for both versions to match? In my mind, translation modules and packages can have their own update and versioning cadence. For example, a translation module might have a version 1 when they first translate a package and then a version 2 if they do a big rewrite. A package can change major versions if an update introduced big breaking changes but the documentation might only change slightly (maybe one or two arguments), so the translation module might only need to create a minor update.

2. Title and description being translations of the original package

I don't think this is great. The title and description should describe what's in the package, so a translation of ggplot2, IMHO, should have a title like "Translation of ggplot2 to X language" (in X language of course) and a description to match. Otherwise the description would be describing something that is not true.

[cregouby]

Hello @eliocamp,

Your remarks are vital, and I would love to clarify a bit:

1. Matching translation module version and package version

My assumption here is the pace of translation module update and the pace of package update are not correlated, thus I consider
the very likely scenario of "after 5 month (or perhaps two years...) of having done once the translation of {torchvision} 0.6.0 into {torchvision.fr} 0.6.0
on a rainy day, I recieve a new issue of 'this function help in torchvision 1.3.0 is poorly translated', it gives both the translator (me) and the end-user raising the issue, an
immediate insight of the effort that needs to be done going from 0.6.0 (translation module version) to 1.3.0." .
The other scenario (which appened for real in 6 out of 7 packages I translated ) is that translation goes in parallel with a pull request to the original package to improve its documentation, making the translation module version
0.6.0.9000 being linked to the development version of the package, not its CRAN version.

IMHO, the use of semantic versionning is a best practice for code as it brings transparency to the end-user of the software, but I see it pointless for the translation module.

2. Title and description being translations of the original package

Here my point of view is subjective as well, and is oriented to ease the end-user searching for a package.
Would you search it in your native language "Paquete R que hace esto y aquello" in spanish ? or would you search for "the translation in spanish of the package that does this and this" ?
Searching for "French Translation of 'hfhub'" (who knows what 'hfhub' is for ?) versus "Interface au Hub Hugging-Face". (I choose this one as the translation is transparent).

Currently none of those search get answered by major search engine, and as translation package are not yet imported by specific search engines like rdocumentation or rdrr, my concern is currently pointless.

Nevertheless, lets compare the result with an end-user perspective :

Semantic versioning and 'translation of...'	P.R. proposal

and a better perspective comes out of filtering packages by the language suffix in the IDE like .fr in the following example:

Please let me know your view, so I can adapt the P.R.