[pre wip] ways to translate help patches.

[Lucarda]

In #3 I'm proposing:

Since the help patches can be translated it could be nice if we find a way to distribute the "translated package" via Deken. Then we can have a way to tell Pd to go and fetch help files in that folder.

Further details on how to do this can be discussed in this thread.

[umlaeute]

translatable help-patches are probably easy to implement (e.g. check for metro-help.pt.pd (if the current locale is pt), and fall back to metro-help.pd if that is missing.

the idea with deken-installable language extension packs is nice (as it's virtually impossible that we will be able to merge translated help-patches into Pd's main branch in time for a new release), but i'm not sure whether it would work out of the box.
deken won't install to the default help-path (and i think we don't really want to change that).

• we might instruct users to add the newly created path to the help-paths. but
  1. i don't know whether this (help-path trickery) actually would works
  2. iirc there's no user-interface in Pd's preferences that allows to set the help-path (which makes it hard for non-console-savy users to perform correctly)
  3. up until now i considered the -helppath flag totally useless and would have loved to see it go away
• we might extend deken to allow for installations of special packages (e.g. references, GUI-translations,...) into "other" places (besides the externals search-path) (though i'm afraid that this will become rather cumbersome quickly)
• in addition, we might extend the user-specific paths to include places for these special packages (e.g. ~/local/lib/pd/help, ~/Documents/Pd/help/), but I think that doesn't work so well with the none-Documents default paths on macOS on Windows.

[Lucarda]

May be we can have a "translations" folder created at the same time ~/Documents/Pd is created (on first run).

Then we use ~/Documents/Pd/translations as the only folder translations go and are searched for.

We can have a new special deken arg "translation" so that the package gets extracted in that folder. e.g
español-5.referencia-(translation).dek

[umlaeute]

the problem with ~/Documents/Pd is that it is

• purely optional, and can be discarded at the users discretion (by just selecting "No" when starting Pd for the first time)
• a GUI-only hack

most people will probably select "Yes" anyhow, but I think a proper solution should be robust against such casualities and provide a uniform way for whatever search path people chose to use.

---

the problem with "a new special deken arg" is that - as proposed - it is an adhoc-solution that does not look very scalable.

• we need something more robust and extensible
• i think "translation" is the wrong tag. afaict we are talking about a documentation overlay, that happens to be in an alternative language. other documentation overlays might include updated reference files in English. the fun part starts when it comes to other overlays - outside the realm of documentation.
• in any case the proposed scheme collides with the current deken-1 filename format (where it would be simply parsed as a library español-5.referencia- (with a trailing dash. wtf) and an architecture of translation. 🤦 )

[Lucarda]

Cool. So we can have a deken-2 filename format file: español-5.referencia.wtf that gets extracted to:

macOS:

~/Library/Pd

Windows:

%AppData%\Pd

GNU/Linux:

~/.local/lib/pd/extra

One thing that I was thinking is to not have the possibility to have more than one "translation package" installed. But may be I'm wrong and there's an easy and robust way of allowing them. Still i think there's no need for that.

[umlaeute]

Am 6. Juni 2021 00:44:14 MESZ schrieb Lucas Cordiviola ***@***.***>:

Cool. So we can have a **deken-2** filename format file: `español-5.referencia.wtf`

that doesn't look like a robust, parsable filename.

that gets extracted to: macOS:> > ` ~/Library/Pd` > > Windows:> > ` %AppData%\Pd `> > GNU/Linux:> > ` ~/.local/lib/pd/extra` >

How's that different from what we already have?

> One thing that I was thinking is to _not_ have the possibility to have more than one "translation package" installed. But may be I'm wrong and there's an easy and robust way of allowing them.

that actually looks like the simplest problem here (if we allow for changes in the pd-core). Just check how other translation systems handle this.

[Lucarda]

that doesn't look like a robust, parsable filename.

I'm thinking that we don't need much parsing for translations. Also I thought that a new extension would act as a first router.

[Español](doc/5.referencia)@2021-06-06.tra

May be the date part is redundant as this can be taken from upload time.

But may be you have other plans for deken-2 filename format. I guess your plans does not include a new file extension and .dek files have to evolve for handling externals, translations and more.

at least in my head is simpler to have (in the server) a new file extension for translations.

May be this can later be discussed as an implementation detail in Deken's repo.

---

~/.local/lib/pd/extra
How's that different from what we already have?

Well is not different but the user specific directory we already have does not depend on decisions from the user.
Please elaborate why we should not use user specific.

---

One thing that I was thinking is to not have the possibility to have
more than one "translation package" installed. But may be I'm wrong and
there's an easy and robust way of allowing them.

that actually looks like the simplest problem here (if we allow for changes in the pd-core).
Just check how other translation systems handle this.

I'm glad this is simple and doable. might be useful for translators.

[Lucarda]

TODO:

Define a folder structure for Translations.

[Lucarda]

Maybe the deken file name could be something:

[<language name>](<description>){<extraction dir>}.trs

[Español]("Ayuda de objetos internos"){ES/doc/5.reference}.trs

[umlaeute]

better (as it's parsable!).

however, i still would like to use a general deken filename format for that, that also covers the general use-case for deken (namely: installing libraries).
in any case

• we need versions!
• the filename needs to map to valid URLs
• the filename must not exceed any filename length limits (for any modern filesystem except 8.3-like fs)
• the filename must be easily creatable by humans and scripts
• we don't want a generic description in the filename
• there is no use in encoding the same information twice ("ES" vs "Español")
  • what do you make of a filename [Español]("Помош за внатрешен објект"){KO/doc/5.reference}.trs?

[umlaeute]

Define a folder structure for Translations.

without much thinking I see two possible solutions:

• use language specific files

  /path/to/Pd/doc/5.reference/bang-help.pd
  /path/to/Pd/doc/5.reference/bang-help.de.pd
  ~/Library/Pd/doc/5.reference/bang-help.pt_br.pd
  

• use language specific folders

  /path/to/Pd/doc/5.reference/bang-help.pd
  /path/to/Pd/doc/5.reference/de/bang-help.pd
  ~/Library/Pd/doc/5.reference/pt_br/bang-help.pd
  

• (there's also the possibility to have a single folder that contains all the translations for a given language, e.g. %AppData%\Pd\pt_br\doc\5.reference\bang-help.pd. i dislike this as it groups data by something rather arbitrary (the language) instead of functionality ("reference patches"))

intuitively i prefer a filename-suffix that indicates the language (bang-help.de.pd), but intuition can be deceptive.

• concise folder-structure
• it requires explicit support for language-suffixes in Pd
• it can get quite messy if you have multiple languages installed.
• might be easier to integrate in the current loading mechanism (i haven't checked)

the directory-suffix could be turned into a more generic solution

• bloated folder-structure
• makes it somewhat harder to compare multiple languages
• rather than explicit support for language-directories, we could add generic support for dynamically adding (persistent) help-paths to Pd (similar to what we already have for search-paths)

[umlaeute]

another rock on the road: what about versioning?

1. the help-patch for [bang] gets translated into portuguese of Pd-0.51
2. [bang] gets super-cow powers for Pd-0.52
3. the master-help patch for [bang] gets updated to document the new powers
4. the user installs Pd-0.52 and the portuguese language pack (for Pd-0.51)

which help-patch do they see?

[Lucarda]

about the filename

ES[v0.51.4]{doc/5.reference}.dek

<locale>[<pd version>]{<extraction dir>}

about folder structure.

At least on normal Pd Windows installations we can discard /path/to/Pd/doc/5.reference/bang-help.de.pd. %programfiles% directories are not writable for Pd or Deken (ie :permission denied warning).

I think the user specific folder is the way to go.

<user specific>/Pd/<dek.locale>/<dek.extraction dir> give us the functionality we need.

i dislike this as it groups data by something rather arbitrary (the language) instead of functionality ("reference patches"))

You can also like it because it groups the "translations" :)

the directory-suffix could be turned into a more generic solution

• bloated folder-structure

"more generic solution" looks good to me. It might be bloated but not at all useless (more the contrary). (also note the above mention to the unwritable Windows thing)

• makes it somewhat harder to compare multiple languages

really?

rather than explicit support for language-directories, we could add generic support for dynamically adding (persistent) help-paths to Pd (similar to what we already have for search-paths).

Isn't this going to break all the "Deken auto install dir". I'm not saying no, just want to make sure if there's a need for that. The way I see it "dynamically adding (persistent) help-paths to Pd" is what is going to be done to the "Deken auto install dir".

another rock on the road: what about versioning?

which help-patch do they see?

I think we must live with it. No clues on what to do about this.

[danomatika]

which help-patch do they see?

I think we must live with it. No clues on what to do about this.

If the folder structure includes the Pd version or there is a meta file, it would be possible to compare...

[Lucarda]

Should be more fine grained with a per file [meta].

We can mention this on #6 so that a [meta] gets into the new [pd reference] sub-patch

EDIT:

This can be less hidden from the translator and just go in [pd reference] (instead of [pd reference]/[meta)]

Edit 2: I think i got totally confused about [meta] and don't like the idea of having that much of *-meta.pd laying around.