Once we get at least the most important parts of the Views Multilingual meta issue done (#2313159: [meta] Make multilingual views work), we should update the hook_help for the Views module to make sure it explains multillingual views.

Here is the help we currently have for Views (links omitted):

About

The Views module provides a back end to fetch information from content, user accounts, taxonomy terms, and other entities from the database and present it to the user as a grid, HTML list, table, unformatted list, etc. The resulting displays are known generally as views.

For more information, see the online documentation for the Views module.

In order to create and modify your own views using the administration and configuration user interface, you will need to enable either the Views UI module in core or a contributed module that provides a user interface for Views. See the Views UI module help page for more information.

Uses

Adding functionality to administrative pages
The Views module adds functionality to some core administration pages. For example, admin/content uses Views to filter and sort content. With Views uninstalled, admin/content is more limited.
Expanding Views functionality
Contributed projects that support the Views module can be found in the online documentation for Views-related contributed modules.

I would propose something like this, as part of the Uses section:
----
Working with multilingual views

If your site has multiple languages and translated entities, each result row in a view will contain one translation of each involved entity (a view can involve multiple entities if it uses relationships). You can use a filter to restrict your view to one language: without filtering, if an entity has three translations it will add three rows to the results; if you filter by language, at most one result will appear (it could be zero if that particular entity does not have a translation matching your language filter choice). If a view uses relationships, each entity in the relationship needs to be filtered separately. You can filter a view to a fixed language choice, such as English or Spanish, or to the negotiated language of the page the view is displayed on (the language that is selected for the page by the language negotiation settings either for Content or User interface).

Independent of filtering, you can choose the display language (the language used to display the entities and their fields) via a setting on the display. Your language choices are the same as the filter language choices, with an additional choice of "Row language", which means to display each entity in the result row using the language that entity has in that particular result row. In theory, this would give you the flexibility to filter to French translations, for instance, and then display the results in Spanish. The more usual choices would be to use the same language choices for the display language and each entity filter in the view, or to use the Row language setting for the display.
----

Note: the UI text for "Row language" and other things mentioned here has not been finalized, and this display setting doesn't even exist yet (see #2217569: Fields row plugin: Translation is non-uniform for base fields, Field UI fields, links; no way to choose "this row's language"), nor do language filters exist yet for all entity types (see parent meta issue). We should not add this to the help until it's actually true, and when we do, we should make sure that the help here matches the UI we ended up with.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

One more thing to be sure to document is that since each row has a language, if you use field-based filters, they need to match those rows.

Here is some proposed text to explain this (paragraph to go between the two proposed above):

Because each result row contains a specific translation of each entity, field-level filters are also relative to these entity translations. For example, if your view has a filter that specifies that the entity title should contain a particular English word, you will presumably filter out all rows containing Chinese translations, since they will not contain the English word. If your view also has a second filter specifying that the title should contain a particular Chinese word, and if you are using "And" logic for filtering, you will presumably end up with no results in the view, because there are probably not any entity translations containing both the English and Chinese words in the title.

jhodgdon’s picture

Priority: Normal » Major

Instead of having one critical parent issue I have been asked to change the status of each child issue.

I think this is probably Major since there is some functionality that is kind of complicated that is not documented.

jhodgdon’s picture

The language settings in particular are still being worked on. See #2394883: Language setup for entity and field based rendering in views is independent, confusing UI, lacking test coverage. I think we need to postpone this issue on that.

ifrik’s picture

Status: Postponed » Needs work

The issue we were waiting for is now fixed.

jhodgdon’s picture

Status: Needs work » Active

No patch yet, so fixing status.

Martin Mayer’s picture

Assigned: Unassigned » Martin Mayer
Martin Mayer’s picture

I read through the suggested text and it seems plausible to me. Therefore I did not make any changes to it.
So I added the above text from the original issue and #1 to hook_help and created a patch.
The help text looks like in the attached screenshot now.

Martin Mayer’s picture

Status: Active » Needs review
jhodgdon’s picture

Status: Needs review » Needs work

Thanks for making the patch!

A few things to address:

a) The headers for Uses items are supposed to start with -ing verbs, so it should probably start with "Creating" or "Working with" or something. Also "multilingual" is misspelled in the patch there. ;)

b) Rather than using P tags, put each paragraph into a separate DD tag.

c) We want to make sure the text in the help matches what the user would see in the UI. So, "negotiated" languages is not the right thing to say. The choices are actually called things like "XYZ language selected by page", and in the Language module, the settings page is called "selection and detection". So that needs to be rewritten.

d) The language display settings have been expanded since that proposed text was written. The row language choices are now "Content language of view row" and "Original language of content in view row". So the wording of that section also needs an update.

I think that's all that needs updating since I first proposed the text back in August. Want to make a new patch and fix it up?

ifrik’s picture

Issue tags: +drupaldevdays
Martin Mayer’s picture

Here is a new patch with the proposed changes from #9 and a screenshot.

Martin Mayer’s picture

Status: Needs work » Needs review
ifrik’s picture

Thanks,

there are still a few technical issues that needs fixing:

  • There is a trailing white space in the <dt> line that needs removing.
  • There are two tabs in the two <dd> lines that need to be replaced by spaces.
  • The link to the Views UI help in the About section needs checking on whether the module is installed. The syntax for that is
    '!views-ui' => (\Drupal::moduleHandler()->moduleExists('views_ui')) ? \Drupal::url('help.page', array('name' => 'views_ui'))  : '#'
    

In the text:

  • There is a dot missing at the end of one of the sentences User interface)

And two issues to take into account for future patches:

  • The usual way of naming/numbering patches is by adding the comment number at the end of the patch. That makes it much easier for anybody to see at what point the patch was introduced.
  • Between one patch and the next, you should make an interdiff, so that reviewers can see what got changed since the last time, instead of going through everything again. A screenshot is useful for visuals, but we not so much for text. See www.drupal.org/patch
ifrik’s picture

Status: Needs review » Needs work
Martin Mayer’s picture

Here is a new patch for #13. Unfortunately I didn't succeed in creating the interdiff. Sorry for that. I will have to see how this works in more detail.

I could not test if checking for the Views UI module works, as it is not possible to deactivate it. I wonder if the check is really necessary as it checks for a core module which is always there, as it can not be deactivated.

Martin Mayer’s picture

Status: Needs work » Needs review
geertvd’s picture

Status: Needs review » Needs work

I could not test if checking for the Views UI module works, as it is not possible to deactivate it.

I was able to uninstall views_ui module and can verify that the check works.

Small issue:

+++ b/core/modules/views/views.module
@@ -44,6 +44,10 @@ function views_help($route_name, RouteMatchInterface $route_match) {
+      $output .= '<dt>' . t('Working with mulitlingual views') . '</dt>';

Typo "mulitlingual" should be "multilingual"

Martin Mayer’s picture

Typo is fixed. #17

Martin Mayer’s picture

Status: Needs work » Needs review
geertvd’s picture

Status: Needs review » Reviewed & tested by the community

Looks good now.
Interdiffs really make reviewing a lot easier though. Instructions on how to make an interdiff can be found here https://www.drupal.org/documentation/git/interdiff

alexpott’s picture

Assigned: Martin Mayer » jhodgdon

Independent of filtering, you can choose the display language (the language used to display the entities and their fields) via a setting on the display. Your language choices are the same as the filter language choices, with an additional choice of "Content language of view row" and "Original language of content in view row", which means to display each entity in the result row using the language that entity has or in which it was originally created. In theory, this would give you the flexibility to filter to French translations, for instance, and then display the results in Spanish. The more usual choices would be to use the same language choices for the display language and each entity filter in the view, or to use the Row language setting for the display.

I'm not sure that the help text should go into the edge cases like "filter to French translations, for instance, and then display the results in Spanish".

Assigning to jhodgdon for a second opinion.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 18: views_help_on_multilingual_2317975-17.patch, failed testing.

jhodgdon’s picture

Assigned: jhodgdon » alexpott

@alexpott: I wrote that suggested text (see comment #1). We need some way to tell people what the setting means, some kind of illustration I think? I don't know if I can give a second opinion.

Status: Needs work » Needs review
jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Test failure seems to be a bot problem. Restoring status.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 18: views_help_on_multilingual_2317975-17.patch, failed testing.

Status: Needs work » Needs review
jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

status restore

alexpott’s picture

Status: Reviewed & tested by the community » Fixed

If @jhodgdon thinks this is good to go. Then so do I. It's a massive improvement on what is there and we can refine later if necessary. Committed b441245 and pushed to 8.0.x. Thanks!

  • alexpott committed b441245 on 8.0.x
    Issue #2317975 by Martin Mayer, jhodgdon, ifrik: Update Views help to...
Gábor Hojtsy’s picture

Issue tags: +D8MI, +language-config

Thanks! Retroactively tagging.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.