Better consistent I18N Java API for all components

[Haprog]

Some of the Vaadin components have an i18n object property on the client side for customizing some texts and setting other localization / internationalization related options.

At least the following components have such properties: DatePicker, DateTimePicker, Upload, LoginForm/LoginOverlay, Crud.

In addition TextField and all components extending it have a i18n.clear property (the screen reader friendly accessible label for the clear button) but there is currently no explicit Java API for setting this. This can probably be ignored for the main purpose of this issue though.

Current implementations

Currently there are at least 2 different ways that the Java API for setting these properties has been implemented.

1. With default values in Java. The login components and Crud automatically initialize a default i18n object with default values on the Java side (populated from a json file in the *-flow repository).
   So if you only want to customize one value from it, you can do this:

   crud.setI18n(CrudI18n.createDefault().setCancel("CANCEL!"));

   or

   crud.setI18n(crud.getI18n().setCancel("CANCEL!"));

   though I think it would be even nicer if this was enough to modify it:

   crud.getI18n().setCancel("CANCEL!");

2. Without default values in Java. DatePicker, DateTimePicker and Upload don't have any default values for these on the server side and expect you to create a new i18n object and set all the possible properties for it to work correctly (otherwise the properties you didn't set will be set to null on client side which will cause issues). See the Java localization demos for DatePicker and Upload. For example DatePicker.getI18n() will return null by default.

   I think the most common use case where you notice this problem is when you want to set the "first day of week" to Monday on a DatePicker (or DateTimePicker) as the default is Sunday. So you want to basically set DatePickerI18n().setFirstDayOfWeek(1) but to be able to do that so that it works you'd need to do something like this:

   datePicker.setI18n(new DatePickerI18n().setWeek("Week")
       .setCalendar("Calendar").setClear("Clear")
       .setToday("Today").setCancel("cancel").setFirstDayOfWeek(1)
       .setMonthNames(Arrays.asList("January", "February", "March",
               "April", "May", "June", "July", "August",
               "September", "October", "November", "December"))
       .setWeekdays(Arrays.asList("Sunday", "Monday", "Tuesday",
               "Wednesday", "Thursday", "Friday", "Saturday"))
       .setWeekdaysShort(Arrays.asList("Sun", "Mon", "Tue", "Wed", "Thu",
               "Fri", "Sat")));

   Or use a workaround like this:

   datePicker.getElement().executeJs("this.set('i18n.firstDayOfWeek', 1)");

What to do

It might be good enough to update DatePicker, DateTimePicker and Upload to work in the same way as LoginForm/LoginOverlay and Crud, but we should consider if there is some even better approach.

The current implementations with default values in Java have those defaults duplicated in the *-flow repository and they need to be maintained in case some of the defaults change in web component. Not sure if this is good or bad, but at least those values are duplicated in two different repositories with this approach.

Could we read the default values from the web component dependency to get them into Java (either build time, or run time)?

It should also be possible to make the Java API work so that only those values that you explicitly set on the i18n object get synchronized to the client (so that values you haven't set would not break the client side by overriding the defaults with null values). If we do this, we don't necessarily need to have the default values known on Java side (though having the default available in Java would still be a nice additional feature). Not sure if there would be a need to support explicitly setting null values to some of the i18n properties (but I'm sure that could be done too).

Would it make sense to make it work so that you don't have to use setI18n() but could just do like this crud.getI18n().setCancel("CANCEL!"); and it would set the property on client side?

Component specific issues for this issue

• https://github.com/vaadin/vaadin-date-time-picker-flow/issues/21

Related issues

• https://github.com/vaadin/vaadin-date-picker-flow/issues/49 (Using Locale info to automatically localize some of the i18n propeties)
• https://github.com/vaadin/vaadin-core/issues/237 (Being able to set localizations globally on app level instead of having to set i18n object individually for every component instance)

[web-padawan]

Some issues related to the current i18n Java API:

https://github.com/vaadin/vaadin-upload/issues/325

https://github.com/vaadin/vaadin-upload/issues/326