Images not displaying on ph-submissions

[jenniferisasi]

@anisa-hawes and I have spent about two hours now trying to find the mistake that is prompting some images not showing in the preview of lessons in the ph-submissions repo. The most baffling one being the case in Sentiment Analysis with syuzhet because it is taking the path to the Spanish version of the lesson: http://programminghistorian.github.io/ph-submissions/images/es/lecciones/analisis-de-sentimientos-r/fig1-syuzhet.png

In sum, in the preview generated in the ph-submissions repo some images are showing and some are not and we cannot find the error anywhere.

If @ZoeLeBlanc and/or @hawc2 could take a look and see if you find the mistake, we'd appreciate it a ton.

[anisa-hawes]

We note also, that this isn't the original path to the images folder: /images/es/lecciones/analisis-de-sentimientos-r/fig1-syuzhet.png, it would simply be /images/analisis-de-sentimientos-r/fig1-syuzhet.png – without es/lecciones

I have double-checked the liquid syntax, the file names and the directory folders... and I think everything is perfect in the .md file >> https://github.com/programminghistorian/ph-submissions/commit/6817acf56060379e245b252b7566b033fc0271e4

[jenniferisasi]

Fixed it! It was about having the images inside the original folder and not a new one.

[anisa-hawes]

Our EN Editorial Guidelines certainly do not explain that images for translations are to be located in the 'original' images folder, in this case: images/analisis-de-sentimientos-r. I have moved them there, and the Preview is perfect now.

As we looked into this, we found that there are multiple other lesson previews on ph-submissions that also display broken images ... and now we understand the reason.

The lesson preview build is looking for the images in a folder that shares its name with that specified in the slug given as original: in the YAML.

[hawc2]

@jenniferisasi @anisa-hawes this ticket can be closed right? Is there any update to editorial guidelines we need to make?

This is also the kind of info that can be made clearer on the ph-submissions/readme.md

[hawc2]

We encountered this problem when going to publish our first English translation, see issue #426 on the ph-submission repo (https://github.com/programminghistorian/ph-submissions/issues/426).

It's not clear to me what the best way to handle this is. Do we consolidate the image directories, or is there another modifcation to be made to the yaml? How does the Spanish team handle it @rivaquiroga ?

The English team is encountering these translation questions for the first time and we'll need to update our docs with info for editors

[acrymble]

@rivaquiroga are you able to respond to @hawc2 please so we can try to close this old issue?

[rivaquiroga]

@hawc2, in the jekyll repo, translated images are stored in the images folder of the original lesson. So you only have one folder per lesson with original and translated images in it. During the editorial process, however, we usually don't do that. Instead, we put the translated images in their own folder because it makes the workflow more manageable and less prone to errors.

• If changes have to be made, it is easier for authors (and editors) to work on a folder that only has the images concerning their own translation, not one that also has the original images and the ones created by finished or active translations.
• It is easier (and safer) for Managing Editors because you know you only have to move to jekyll the images in that folder. You avoid overwriting files, forgetting one, etc.
• You can check the image naming conventions with phimages.py

In ph-submissions, you will only see in the lesson preview the images stored in the folder that matches the lesson's filename. However, when you add the “original” field to the YAML header, the images stored in the folder that matches the original lesson filename will be rendered. Sometimes the translation does not modify any image, so pointing to the original lesson is the right choice. If the translation translated all the images, you could choose not to add the "original" field to the YAML until you move the lesson to jekyll. That way, only the translated images will be rendered. But sometimes you have mixed images. And in those cases, you can't see them all rendered. So you have to choose which ones you prefer to be shown. At least in the Spanish team, the tradition has been to prefer rendering the original images. That is why when we start a new translation, we not only include the link to the lesson preview on the first message but also to the folder with the images. So, if you have mixed images, you know where to find the translated ones and check how they look. Not having all images rendered in ph-submissions' previews has not been an issue in the past for us because we know that, as long the filenames are correct, everything will look right in the published version. And we can check the Netlify preview before publishing to check everything is rendered as expected.

[rivaquiroga]

BTW, before the use of liquid syntax, this was not always a problem because published lessons used to have a direct link to the images in the jekyll repo. So when translating one of those older lessons, original and translated images are all rendered in ph-submission, as long as you don't add the "original" field to the YAML. We add it when moving the file to the jekyll repo.

Here is an example of this situation:

• lesson file: https://raw.githubusercontent.com/programminghistorian/ph-submissions/gh-pages/es/publicadas/traducciones/sitios-estaticos-jekyll-github-pages.md
• preview with both original and translated images rendered: https://programminghistorian.github.io/ph-submissions/es/publicadas/traducciones/sitios-estaticos-jekyll-github-pages

[hawc2]

Thanks @rivaquiroga! This is really clarifying. Some of this info will need to be added to the Editor guidelines as part of our upcoming conversations.

It seems to me the best practice to standardize here would be that the original yaml info not be added until the lesson is moved over to Jekyll, which would only require a slight addition to the Editor Guidelines for the Managing Editor when dealing with translations.

Right now, on the Editor Guidelines, there's some pretty confusing/outdated guidelines for how the Managing Editor should move files. It might be best to open a separate ticket to address those changes and include this one with others. What do you think @anisa-hawes?

In the meantime, I'll proceed with publishing this lesson and focus on everything rendering correctly on the Jekyll site

[acrymble]

Just a quick note that @anisa-hawes is on leave this week.

[anisa-hawes]

Thank you @hawc2 for re-asking the question and to @rivaquiroga for explaining how the ES team handle this.

I must admit, it is still confusing to me...

@jenniferisasi and I were chatting about this again a few weeks ago, as I tried to clarify things in my mind...

My understanding was that the YAML for a translation must include the field original: but omit the field slug:. Am I correct that this problem only arises when an .md includes both of those fields?

@rivaquiroga does your workflow of saving translated images in their own folder, not cause any original images to appear to be broken on the ph-submissions Preview?

I wonder if the confusions and errors when it comes to moving the files over to Jekyll could be avoided if we agree on a fixed naming convention as discussed in Issue #2360.

I'd like to suggest that we agree on the following pattern (which uses the choice of OR or TR prefix as shorthand to indicate original or translation/traducción/traduction/tradução).

For an original lesson:

or-lesson-image-name-1.png
or-lesson-image-name-2.png
or-lesson-image-name-3.png
or-lesson-image-name-4.png

For a translation which uses all new images:

tr-lesson-image-name-1.png
tr-lesson-image-name-2.png
tr-lesson-image-name-3.png
tr-lesson-image-name-4.png

For a translation which creates some new images but keeps others as original:

or-lesson-image-name-1.png
or-lesson-image-name-2.png
tr-lesson-image-name-2.png
or-lesson-image-name-3.png
or-lesson-image-name-4.png
tr-lesson-image-name-4.png

[hawc2]

@anisa-hawes did we clarify this during the translation meeting? I think we can probably close this and update our documentation with the main info

[anisa-hawes]

Thank you, @hawc2.

I think there are still several different workflows.

In our meeting, Riva explained that the ES team's approach is to save translated images in a new folder which shares its name with the translated lesson, rather than in the original images folder. This means that any translated images appear to be broken in the ph-submissions Preview, because they are not found within the folder specified in the YAML field original:. The ES team choose to work in this way because the images folders have become very confusing, with many different approaches to naming images.

What I think we agreed in the meeting was that the only way to solve this problem is to agree a naming convention that we all share.

Since making the suggestions above, I realised that we also need to be able to differentiate between translations. Because many original lessons are translated into two or three languages. So the pattern I've proposed might also need to include en, es, fr, pt to differentiate images as a lesson grows.

Here's an example for an original Spanish lesson:

or-es-lesson-image-name-1.png
or-es-lesson-image-name-2.png
or-es-lesson-image-name-3.png
or-es-lesson-image-name-4.png

And for a Portuguese translation of that lesson which uses all new images:

tr-pt-lesson-image-name-1.png
tr-pt-lesson-image-name-2.png
tr-pt-lesson-image-name-3.png
tr-pt-lesson-image-name-4.png

For a Portuguese translation which creates some new images but keeps others as original:

or-es-lesson-image-name-1.png
or-es-lesson-image-name-2.png
tr-pt-lesson-image-name-2.png
or-es-lesson-image-name-3.png
or-es-lesson-image-name-4.png
tr-pt-lesson-image-name-4.png

If you were the Portuguese Managing Editor preparing to move the files (above) over to Jekyll for publication, you would only need to move those with the tr-pt prefix.

--

Here's an example of how that file list might look if the lesson is later translated into French. Again, this translation creates some new images but keeps others as they were in the Spanish original:

or-es-lesson-image-name-1.png
or-es-lesson-image-name-2.png
tr-pt-lesson-image-name-2.png
tr-fr-lesson-image-name-2.png
or-es-lesson-image-name-3.png
tr-fr-lesson-image-name-3.png
or-es-lesson-image-name-4.png
tr-pt-lesson-image-name-4.png
tr-fr-lesson-image-name-4.png

If you were the French Managing Editor preparing to move the files (above) over to Jekyll for publication, you would only need to move those with the tr-fr prefix.

--

Does this make sense as a proposal?

One of the things Riva and I discussed was the idea that when we start a new translation (going forwards) we could go through the process of re-naming the original images for particular lessons. This is something that might be possible for me to do as part of an initial lesson set-up phase.

In the end, I think this might be worthwhile for the following reasons:

• Images in ph-submissions Preview will always display
• Managing Editors will not be confused/make mistakes when they are identifying which images to move over to Jekyll
• Lesson Maintenance will be simpler because images will be named consistently

I very much welcome feedback on this, and am aware that there might be a complexity I haven't thought of somewhere... !

[hawc2]

This generally sounds like a good solution to me!

On Thu, Nov 10, 2022, 12:41 PM Anisa Hawes @.***> wrote:

Thank you, @hawc2 https://github.com/hawc2.

I think there are still several different workflows.

In our meeting, Riva explained that the ES team's approach is to save translated images in a new folder which shares its name with the translated lesson, rather than in the original images folder. This means that any translated images appear to be broken in the ph-submissions Preview, because they are not found within the folder specified in the YAML field original:. This is because the images folders have become very confusing, with many different approaches to naming images.

What I think we agreed in the meeting was that the only way to solve this problem is agreeing a naming convention that we all share.

Since making the suggestions above, I realised that we also need to be able to differentiate between translations. Because many original lessons are translated into two or three languages. So the pattern I've proposed might also need to include en, es, fr, pt to differentiate images as a lesson grows.

Here's an example for an original Spanish lesson:

or-es-lesson-image-name-1.png or-es-lesson-image-name-2.png or-es-lesson-image-name-3.png or-es-lesson-image-name-4.png

And for a Portuguese translation of that lesson which uses all new images:

tr-pt-lesson-image-name-1.png tr-pt-lesson-image-name-2.png tr-pt-lesson-image-name-3.png tr-pt-lesson-image-name-4.png

For a Portuguese translation which creates some new images but keeps others as original:

or-es-lesson-image-name-1.png or-es-lesson-image-name-2.png tr-pt-lesson-image-name-2.png or-es-lesson-image-name-3.png or-es-lesson-image-name-4.png tr-pt-lesson-image-name-4.png

If you were the Portuguese Managing Editor preparing to move the files (above) over to Jekyll for publication, you would only need to move those with the tr-pt prefix.

--

Here's an example of how that file list might look if the lesson is later translated into French. Again, this translation creates some new images but keeps others as they were in the Spanish original:

or-es-lesson-image-name-1.png or-es-lesson-image-name-2.png tr-pt-lesson-image-name-2.png tr-fr-lesson-image-name-2.png or-es-lesson-image-name-3.png tr-fr-lesson-image-name-3.png or-es-lesson-image-name-4.png tr-pt-lesson-image-name-4.png tr-fr-lesson-image-name-4.png

If you were the French Managing Editor preparing to move the files (above) over to Jekyll for publication, you would only need to move those with the tr-fr prefix.

--

Does this make sense as a proposal?

One of the things Riva and I discussed was the idea that when we start a new translation (going forwards) we could go through the process of re-naming the original images for particular lessons. This is something that might be possible for me to do as part of an initial lesson set-up phase.

In the end, I think this might be worthwhile for the following reasons:

• Images in ph-submissions Preview will always display
• Managing Editors will not be confused/make mistakes when they are identifying which images to move over to Jekyll
• Lesson Maintenance will be simpler because images will be named consistently

I very much welcome feedback on this, and am aware that there might be a complexity I haven't thought of somewhere... !

— Reply to this email directly, view it on GitHub https://github.com/programminghistorian/jekyll/issues/2578#issuecomment-1310658356, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADXF4EGZEWADUYGNDVT7LQ3WHUXWLANCNFSM5V4BOW5Q . You are receiving this because you were mentioned.Message ID: @.***>

[anisa-hawes]

Maybe I will add that, ideally, the lesson-image-name part of the file name would be the lesson slug. For example:

or-en-analyzing-documents-with-tfidf-1.png
or-en-analyzing-documents-with-tfidf-2.png
or-en-analyzing-documents-with-tfidf-3.png
tr-fr-analyse-de-documents-avec-tfidf-3.png
or-en-analyzing-documents-with-tfidf-4.png
tr-fr-analyse-de-documents-avec-tfidf-4.png

[anisa-hawes]

A new Wiki page has been created to document this Image Naming Convention. This page represents part of a series of guideline documents I am developing to support our ProgHist publishing team with technical aspects of lesson set-up and file management.