Clean up language (types) bootstrap function naming and documentation

+++ b/core/includes/language.incundefined
@@ -11,11 +11,41 @@
+ * Choose a language for the given type based on language negotiation settings.

ChooseS I know that the old docs made the same mistake but as you're writing new ones.

+++ b/core/includes/language.incundefined
@@ -11,11 +11,41 @@
+/**
+ * Return information about all defined language types.
+ *
+ * @see hook_language_types_info().
+ * @return

ReturnS

The @see should be in the end with a newline above it.

+++ b/core/includes/language.incundefined
@@ -11,11 +11,41 @@
+ *   An associated array of language type information arrays keyed by type ¶

trailing whitespace

+++ b/core/modules/locale/locale.api.phpundefined
@@ -65,13 +65,19 @@ function hook_language_switch_links_alter(array &$links, $type, $path) {
- *   the following key-value pairs:
+ *   An associative array of language type definitions. ¶
+ * ¶
+ *   Each language type has an identifier key which is used as the name for the
+ *   global variable corresponding to the language type in the bootstrap phase. ¶
+ *
+ *   The language type definition is an associative array that may contain the
+ *   following key-value pairs:
  *   - "name": The human-readable language type identifier.
  *   - "description": A description of the language type.
- *   - "fixed": An array of language provider identifiers. Defining this key
- *     makes the language type non-configurable.
+ *   - "fixed": A fixed array of language provider identifiers to use to ¶
+ *     initialize this language. Defining this key makes the language type
+ *     non-configurable and will always use the specified providers in the

Trailing whitespace party

-25 days to next Drupal core point release.

Updated issue summary.

+++ b/core/includes/bootstrap.incundefined
@@ -2620,13 +2620,19 @@ function drupal_language_initialize() {
+ *   An array of key-values pairs where the key is the language type name and ¶

another one

You should search for an "remove trailing whitespaces on save" option in your text editor. Makes your life easier ;)

-26 days to next Drupal core point release.

http://drupal.org/node/1346890 i made this page, you will like it

Updated issue summary.

Do we want to switch to the scope terminology in this patch? If so I'd go for the singular form:

language_scope_get_defaults()
language_scope_get_all()
language_scope_get_configurable()
language_scope_initialize()
language_scope_info() 
hook_language_scope_info()
hook_language_scope_info_alter()
language_scope_disable()
language_scope_set()

Anyway:

+++ b/core/includes/language.inc
@@ -11,11 +11,42 @@
+ *   An associated array of language type information arrays keyed by type
+ *   names. Base on information from hook_language_types_info().

Associated? I think we normally use the "indexed" or "associative" terms. Also "Base" should be "Based", I guess.

+++ b/core/includes/language.inc
@@ -113,12 +145,12 @@ function language_types_set() {
+  // Ensure that subsequent calls of language_types_get_configurable() return the

Wrong comment wrapping.

+++ b/core/modules/locale/locale.api.php
@@ -88,6 +94,7 @@ function hook_language_types_info() {
+ * @see hook_language_types_info().

IIRC there should be a blank line before the @param(s).

+++ b/core/modules/locale/locale.api.php
@@ -65,13 +65,19 @@ function hook_language_switch_links_alter(array &$links, $type, $path) {
+ *     non-configurable and will always use the specified providers in the
+ *     given priority order.

"given" should be moved one line up.

-28 days to next Drupal core point release.

After a little mail conversation with Gábor, I'm going to work on the switch scope terminology

@rvilar:

Great! Also LANGUAGE_TYPE_* constants will need to be updated.

Hm. Where did we discuss "scope"? When I read #12 I had no idea what a scope is and that the proposal was to rename language types to scopes. I'm not sure whether that term is really an improvement over the current, and thus, whether it's worth to break and change the API and what people have learned (aside from the locale/language function name changes). It might be, but hm.

@sun:

I proposed this change in #1222106-4: Unify language negotiation APIs, declutter terminology and Gabor seemed to approve it. I spoke with @chx in IRC proposing him the scope terminology and he said something like "everything is better than type". If we want to go the scope way @rvilar is available to write the patch, if not no worries, but the patch in #9 needs work.

I guess we can simply move on and discuss the terminology in parallel. May or may not be a simple rename in the final patch in the end, depending on the discussion. We need to change the function names either way.

I attach a patch with the rename done. Please, review and comment on that.

Yes. I've applied all the suggestions and corrections.

Now we have two mostly RTBC patches, let's discuss which one we prefer :)

As I said, if we want to change the type terminology (which might make sense) I'd go for scope, since IMHO it make more clear what the actual meaning is: for instance, I'm thinking of a page where the admin menu and the local tasks have the admin language, the rest of the UI has the site default language and a translated content is being showed. Type fits here as well, but if we want to change it, scope is my favorite alternative.

Maybe what we want is a committer feedback here? I doubt we will get any from @chx.

@rvilar:

Thanks, I had a quick look to the patch and found some comments not wrapping correctly:

+++ b/core/includes/language.inc
@@ -11,54 +11,85 @@
+ * A language scope maybe configurable or fixed. A fixed language scope is a scope
...
+++ b/core/includes/language.inc
@@ -11,54 +11,85 @@
+ *   If set to FALSE retrieves values from the actual language scope definitions.
...
+++ b/core/includes/language.inc
@@ -68,57 +99,58 @@ function language_types_configurable($stored = TRUE) {
+  // whether the 'fixed' key is defined. Non-configurable (fixed) language scopes
...
+++ b/core/includes/language.inc
@@ -68,57 +99,58 @@ function language_types_configurable($stored = TRUE) {
+  // Ensure that subsequent calls of language_scope_get_configurable() return the
...
+++ b/core/modules/locale/locale.admin.inc
@@ -72,11 +72,11 @@ function _locale_languages_configure_form_language_table(&$form, $type) {
+    // List the provider only if the current scope is defined in its 'scopes' key.
...
+++ b/core/modules/locale/locale.admin.inc
@@ -187,29 +187,29 @@ function theme_locale_languages_configure_form($variables) {
+  // Update non-configurable language scopes and the related language negotiation
...
+++ b/core/modules/locale/locale.api.php
@@ -104,9 +111,9 @@ function hook_language_types_info_alter(array &$language_types) {
+ *   - "scopes": An array of allowed language scopes. If a language provider does

Wrong comment wrapping.

"scope" might be the best option. But I think we should ideally ask some developers who are unfamiliar with this issue to answer this open question:

What is or what kind of functionality would you associate with a Language Scope API?

(you can replace "Scope" with "Type", "Context", etc)

Speaking as myself when I first encountered the term 'language type' it made absolutely no sense to me. I can only imagine how my understanding would be with the term 'language scope' back when I started out, but now it makes more sense to me than language type. Language scope to me means on what 'areas' the language settings will apply. Language type does not let me imagine what this could mean in the context of Drupal at all. Language context is not bad either, but I feel scope is better, because it probably will not be used elsewhere in Drupal, and therefore be less confounding when encountering other parts of Drupal with similar names.

It would allow you to translate mouthwash into different languages

LOL

I think we need Dries' feedback. As Tor Arne Thune was pointing out in #26 probably for someone needing to deal with ML aspects scope would be a bit more accessible than type, but docs will be a key factor anyway. We need to understand if the time spent on polishing the terminology is worth this gain or whether we should leave it as is.

No problem at all with that. I just want to have a link to show to anyone will say the language type does not mean anything ;)

I'll throw in my 2 cents... I prefer "type" rather than "scope" only because it is a more familiar term (in general) and I don't normally see "scope" used in programming. I definitely do have a strong aversion to using "context" only because of the Context module and CTools context and other uses of the word within Drupal.

[update] After seeing the drupal_language_types() function, I understand why "scope" was proposed. It does seem more "appropriate" though I still like the sound of "type" better for some intangible reason.

function drupal_language_types() {
  return array(
    LANGUAGE_TYPE_INTERFACE => TRUE,
    LANGUAGE_TYPE_CONTENT => FALSE,
    LANGUAGE_TYPE_URL => FALSE,
  );
}

What about language group? Or, category?

Kristen

Rerolled #9 with the cosmetic fixes proposed in #12 applied. The patch "logic" is unchanged.

I'd be glad If @Dries could let us know his opinion about whether we need to change the "language type" terminology (see #16 and following). IMO his feedback has a double value here: as the project lead's and as the one of a core developer non deeply involved in multilingual stuff.

If we decide to keep "type" I'd say this is ready to go in.

#33: language_types-1416392-33.patch queued for re-testing.

It seems some new tests got in meanwhile...

I'l have a look to tests tonight if someone does not beat me to it before
(feel free ;)

Tests were failing due to #1331370: [Upgrade path broken] Stored include paths need to be updated to /core before running the upgrade path that introduced a new call to language_types() in the upgrade preparation phase.

Looks good... thanks @plach!

Kristen

Assigning this to myself so I can comment on the terminology (as requested above). I think I should be able to do this tomorrow.

#40: language_types-1416392-40.patch queued for re-testing.

I'm not sure $scope is better than $type. We can discuss that in another issue. In the mean time, this patch looks like great progress. Committed to 8.x. Sorry for holding this one up.