search

XLSForm / pyxform

A Python package to create XForms for ODK Collect.
BSD 2-Clause "Simplified" License
80 stars 136 forks source link

Improve error message when some columns are missing languages #609

Open yanokwa opened 2 years ago

yanokwa commented 2 years ago

Given a form with a mix of columns with languages, we show a very confusing error message.

Screen Shot 2022-04-27 at 10 48 50

Language 'English (en)' is missing the survey media::image column. Language 'default' is missing the survey label column.

The first line is great, but the second line is very hard to understand. Maybe it could say "Some of your columns (usually label or media) are missing translations."

lindsay-stevens commented 2 years ago

Hi @yanokwa could you please:

  1. add a markdown version or link to the full XLSForm in question?
  2. clarify what is confusing about the current wording? e.g. the grammar, or the reference to the unnamed/default language as 'default', or the formatting of the message e.g. no quotes around 'survey' or 'label', etc?

In the PR for this #571 there were a few iterations of the error message formatting, so tagging @lognaturel. The suggested wording seems like it might be useful for simple forms but maybe not so much for large forms (many columns/languages). Also, pyxform knows exactly which columns are missing translations so I'm not sure about making the message vague.

lognaturel commented 2 years ago

I think the fundamental problem here is that there's only one language as far as the user is concerned so seeing two errors is confusing. It so happens that fixing the first one will make the second one go away but a user might waste a bunch of time trying to figure out what the second one means before fixing the first.

Maybe we should omit any message about the "default" language? I can't think of a case where users would want to mix named languages with the unnamed one. The risk would be that someone would have full translations for named languages and partial translations for the unnamed one. I would be surprised by that. If it happened, they'd be no worse off than before #571.

lindsay-stevens commented 2 years ago

How about some explanatory text, i.e. add a header to the existing message:

Missing translations were detected. Learn more: https://xlsform.org/en/#multiple-language-support
Language 'English (en)' is missing the survey media::image column.
Language 'default' is missing the survey label column.

Then add the following paragraph to the docs:

For each translatable column used in the form, there should be a translation column for each language. For example if you have an English, Spanish and Portuguese label, but only an English hint, then a Spanish and Portuguese hint are needed. If you do not intend to use the 'default' / unnamed language (i.e. 'label', 'hint', etc. with no language suffix), then ensure that all used translatable columns have a language suffix. Omitting translations for some used columns or languages can cause unexpected or confusing form behavior when collecting data. The translatable columns are listed here: https://xlsform.org/en/ref-table/

Or alternatively, copy or link to the Warning box text from here: https://docs.getodk.org/form-language/

yanokwa commented 2 years ago

I like the additional header and the additional paragraph. I think historically we link to xlsform.org, so I'd bias to keep doing that.

What was confusing for me was the text about a "default" language because it assumes a lot of context that a form designer might not have. I'd prefer dropping that line.