Here is a proposal from the com_localise team - Comments?

[infograf768]

While coding com_localise, we found necessary to improve the metas for
the language ini files in order:

1. to comply to Translation Policy (what is compulsory, editable or
not depending on cases)
2. to make it easier to make installation packs in all cases of
figure.
3. to make it easier to edit in com_localise by improving the UI.
4. to deal easily with inis placed in the 3pds extensions language
folder.

The different cases concerned are:

1. packs for Core inis Site or Administrator (make sure we only
include Core files)
2. packs for Core inis both Site and Administrator (make sure we only
include Core files)
3. packs for 4th party translating 3pds inis. Files have to be
installed in Core site language folder or/and Core Administrator
language folder. (Plugins are a special case where we may have to
create packs that install the same file in both site and admin
folders.)

This is what we came to (between parenthesis are comments concerning
com_localise features. Displayed or not is a com_localise UI matter):

Meta Core admin and site inis

# $Id: Not compulsory. Not displayed
#@Core Compulsory, non editable
#@Client Compulsory, editable. Can be : Site or Administrator (this
is the only meta difference between site and administrator ini files
for Core)
#@Version Compulsory. Editable
#@Desc Compulsory. Editable. Default: Joomla! English(GB)
#@Date Compulsory. Editable
#@Author Compulsory. Editable. Default: Joomla! Project
#@Copyright Compulsory. Non editable. Default: (C) 2005 - 2009 Open
Source Matters. All rights reserved. (may be good to define a way to
change 2009 to 2010, etc. globally)
Multiple copyrights Not Compulsory. Editable.
#@License Compulsory. Default: http://www.gnu.org/licenses/gpl-2.0.html
GNU/GPL . Not editable.
#Note Compulsory. Not displayed. Default: All ini files need to be
saved as UTF-8 - No BOM . Not editable.

Meta Core Installation inis

# $Id: Not compulsory. Not displayed
#@Core Compulsory, non editable
#@Client Compulsory, non editable. Default: Installation
#@Version Compulsory. Editable
#@Desc Compulsory. Editable. Default: Joomla! English(GB)
#@Date Compulsory. Editable
#@Author Compulsory. Editable. Default: Joomla! Project
#@Copyright Compulsory. Non editable. Default: (C) 2005 - 2009 Open
Source Matters. All rights reserved. (may be good to define a way to
change 2009 to 2010, etc. globally)
Multiple copyrights NO
#@License Compulsory. Default: http://www.gnu.org/licenses/gpl-2.0.html
GNU/GPL . Not editable.
#Note Compulsory. Not displayed. Default: All ini files need to be
saved as UTF-8 - No BOM . Not editable.

Meta 3PD inis

# $Id: Not compulsory. Not displayed
#@Core NO
#@Client Compulsory, editable. Can be : Site or Administrator (see if
we use "Site,Administrator" for 3pd plugins which ini is used in both
interfaces.)
#@Version Compulsory. Editable
#@Desc Compulsory. Editable. (Name of extension, name of language)
#@Date Compulsory. Editable
#@Author Compulsory. Editable.
#@Copyright Compulsory. Editable.
Multiple copyrights Not compulsory. Editable. Can be used by
Translators
#@License Compulsory. Default: http://www.gnu.org/licenses/gpl-2.0.html
GNU/GPL . Not editable.
#Note Compulsory. Not displayed. Default: All ini files need to be
saved as UTF-8 - No BOM . Not editable.

[infograf768]

I was asked to show here what would be the difference with a typical
ini Core file as we have now:

Today, we have

# $Id: en-GB.ini 11557 2009-02-01 03:33:14Z robs $
# Joomla! Project
# Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
# License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see
LICENSE.php
# Note : All ini files need to be saved as UTF-8 - No BOM

We would have now on

# $Id: en-GB.ini 11557 2009-02-01 03:33:14Z robs $
#@Core
#@Client Site
#@Version 1.6 pre-alpha
#@Desc Joomla! English(GB)
#@Date February 2009
#@Author Joomla! Project
#@Copyright (C) 2005 - 2009 OpenSource Matters. All rights reserved.
#@License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL.
#Note : All ini files need to be saved as UTF-8 - No BOM .

[Chris Davenport]

The use of the @ symbol should be avoided unless you are going to use valid phpDocumentor tags.  Some of the tags you are proposing, such as @core and @client are not valid and will cause phpDocumentor to throw an error.

Chris.

2009/2/23 infograf768 <infog...@gmail.com>

[infograf768]

We have no issue using only the # symbol as we can parse it the same.
Or #%
or whatever we are told to.

On 23 Feb, 18:05, Chris Davenport <chris.davenp...@joomla.org> wrote:
> The use of the @ symbol should be avoided unless you are going to use valid
> phpDocumentor tags.  Some of the tags you are proposing, such as @core and
> @client are not valid and will cause phpDocumentor to throw an error.
>
> Chris.
>

> 2009/2/23 infograf768 <infograf...@gmail.com>

>
>
>
> > I was asked to show here what would be the difference with a typical
> > ini Core file as we have now:
>
> > Today, we have
>
> > # $Id: en-GB.ini 11557 2009-02-01 03:33:14Z robs $
> > # Joomla! Project
> > # Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.

> > # Licensehttp://www.gnu.org/licenses/gpl-2.0.htmlGNU/GPL, see

[Rob Schley]

You are going to parse this data and display it? Why not just use an XML file like everything else?

Rob

[Sam Moffatt]

Because the metadata is file specific, its similar to the phpdoc
statements we in part use presently and whilst the system will most
likely not care, the localisation manager does use this information,
particularly the 'core' tag when building a core language pack.
Consider all of the third party language files in a /langauges/xx-XX
directory, we have core files, we have translated versions of core
files by third parties (our translation teams), we have third party
language files for third party extensions with their translations and
we may also have what i'm calling 'fourth party' translations: e.g.
translations of third party extensions done by third parties
completely unrelated to the original third party (perhaps it should be
sixth party?). If we have an xml for each of these cases then thats
potentially going to add up to a lot of xml files that need to be
stored somewhere as opposed to transparently hiding them in the actual
files themselves. We already have some form of metadata at the moment
for language files however it isn't structured well.

Sam Moffatt
http://pasamio.id.au

[Andrew Eddie]

Can I ask a silly question (because I've forgotten the answer).

Why do we need so much meta in the individual ini files?  Is there really a need for anything other than Date/Version (file version, not Joomla version), Author, Copyright and License?

Regards,
Andrew Eddie

2009/2/24 infograf768 <infog...@gmail.com>

[infograf768]

The proposal is (after Chris input, I took of the @)
I comment the reasons for each line which are not Date, Author,
Copyright, License


# $Id: en-GB.ini 11557 2009-02-01 03:33:14Z robs $ // this is made by
SVN when the language files are created/updated this way. Majority of
Translators do not use SVN, thus the need for some supplementary metas
as described below.

# Core // this defines if an ini file is Core or 3pd. Reason is
package making. Until now all inis in the core language folders were
included in the a pack when using the Translation Manager. There was
no way to separate these.

# Client Site // this is to avoid confusion between Site and
Administrator ini files when they have the same name. Also of use when
creating packages. For Core and also for 3pds.

# Version 1.6 pre-alpha // In fact, this is not the Joomla version
only. This becomes necessary when the Translation Team coordination
has to control the update of packs provided by the Translation Teams
when Joomla version is updated, as we can't control when a specific
ini has been updated or not. Can be # Version 1.6v1, v2 or # Version
1.6.1, 1.6.1v1, etc.• 1.6 or 1.6.1 are related to the Joomla version,
v1 or v2 etc. to the language pack version.

# Desc Joomla! English(GB) // Used to know which language is concerned
and for which specific usage i.e. Jooma core or 3pd. For 3pd, the name
of extension should be added instead of Joomla! i.e. # Desc
Mycomponent English(GB). This provides for easier identification of
the file when SVN is not used i.e. when edited manually or through
com_localise.

# Date February 2009

# Author Joomla! Project

# Copyright (C) 2005 - 2009 OpenSource Matters. All rights reserved.

# License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL.

# Note : All ini files need to be saved as UTF-8 - No BOM . // the NO
BOM should be taken of if the patch implemented in 1.5 is ported to
1.6.

Hope this makes sense and that we can go on.
JM

On 2 Mar, 08:50, Andrew Eddie <mambob...@gmail.com> wrote:
> Can I ask a silly question (because I've forgotten the answer).
> Why do we need so much meta in the individual ini files?  Is there really a
> need for anything other than Date/Version (file version, not Joomla
> version), Author, Copyright and License?
>
> Regards,
> Andrew Eddie
>

> 2009/2/24 infograf768 <infograf...@gmail.com>

>
>
>
> > I was asked to show here what would be the difference with a typical
> > ini Core file as we have now:
>
> > Today, we have
>
> > # $Id: en-GB.ini 11557 2009-02-01 03:33:14Z robs $
> > # Joomla! Project
> > # Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.

> > # Licensehttp://www.gnu.org/licenses/gpl-2.0.htmlGNU/GPL, see

[Andrew Eddie]

Thanks JM. Still got some questions though. If we need them we need
them, but just seems to be a lot in there that can be inferred from
other sources.

> # $Id: en-GB.ini 11557 2009-02-01 03:33:14Z robs $  // this is made by
> SVN when the language files are created/updated this way. Majority of
> Translators do not use SVN, thus the need for some supplementary metas
> as described below.

Yeah, that one is fine.

> # Core // this defines if an ini file is Core or 3pd. Reason is
> package making. Until now all inis in the core language folders were
> included in the a pack when using the Translation Manager. There was
> no way to separate these.

So what happens? Does the package maker parse each file to look for
that attribute?

Why aren't you working off the list of core extensions in the database?

> # Client Site // this is to avoid confusion between Site and
> Administrator ini files when they have the same name. Also of use when
> creating packages. For Core and also for 3pds.

We have the problem with components as well. The solution is to put
the "client" files in sub-folders of the package file (been available
since Joomla 1.0). I really don't think this is necessary to nominate
as com_localise can work it all out.

> # Version 1.6 pre-alpha // In fact, this is not the Joomla version
> only. This becomes necessary when the Translation Team coordination
> has to control the update of packs provided by the Translation Teams
> when Joomla version is updated, as we can't control when a specific
> ini has been updated or not. Can be # Version 1.6v1, v2 or # Version
> 1.6.1, 1.6.1v1, etc.•  1.6 or 1.6.1 are related to the Joomla version,
> v1 or v2 etc. to the language pack version.

I can live with the Joomla version, but why couldn't the Id tag (the
revision number) serve the same role as the "v" numbers. Or, I am not
understanding why the "v" numbers are significant.

> # Desc Joomla! English(GB) // Used to know which language is concerned
> and for which specific usage i.e. Jooma core or 3pd. For 3pd, the name
> of extension should be added instead of Joomla! i.e. # Desc
> Mycomponent English(GB). This provides for easier identification of
> the file when SVN is not used i.e. when edited manually or through
> com_localise.

I have a problem with this being different for core and 3pds - that's
confusing. But why for core do you need the language name when it can
be looked up in the XML file. The file name also tells you what the
language is. For 3pd's, the file name also tells you the language and
where it applies to (which extension). Just don't like the idea of
doubling up information that we already have, that's all.

Regards,
Andrew Eddie

[JM Simonet]

>Thanks JM. Still got some questions though. If we need them we need
>them, but just seems to be a lot in there that can be inferred from
>other sources.
>
>> # $Id: en-GB.ini 11557 2009-02-01 03:33:14Z robs $ // this is made by
>> SVN when the language files are created/updated this way. Majority of
>> Translators do not use SVN, thus the need for some supplementary metas
>> as described below.
>
>Yeah, that one is fine.

Sure, but please do not forget that most TT or 3pd don't use svn.

>
>> # Core // this defines if an ini file is Core or 3pd. Reason is
>> package making. Until now all inis in the core language folders were
>> included in the a pack when using the Translation Manager. There was
>> no way to separate these.
>
>So what happens? Does the package maker parse each file to look for
>that attribute?

Yes. And it works easily and flawlessly. It also
permits differentiating files in com_localise UI.

>
>Why aren't you working off the list of core extensions in the database?

Much more complex IMO and does not take into
account the main en-GB.ini or the specific
xx-XX.whatever.menu.ini, if I do not mistake.
+ the fact that as extensions are added, nothing
differentiate them from Core ones in the db as
far as I could see in jos_extensions.

>
>> # Client Site // this is to avoid confusion between Site and
>> Administrator ini files when they have the same name. Also of use when
>> creating packages. For Core and also for 3pds.
>
>We have the problem with components as well. The solution is to put
>the "client" files in sub-folders of the package file (been available
>since Joomla 1.0). I really don't think this is necessary to nominate
>as com_localise can work it all out.

We do know these files are in sub-folders to be
installed in their proper place, whether in core
folders or in their respective language folders
and the packaging will take this into account
when creatins specific language install packs,
only possible in core folders.
The meta makes it much easier to deal with.
Think of 2 files with same name,
one is in administrator/components/mycomponent/language/xx-XX/
the other in components/mycomponent/language/xx-XX/
or both in the respective Core language folders
Com_localise will pick these files and make a
combined install pack for a new language for this
component.
Another issue are the plugins who may need their
inis (when proposed by the 3pd dev in the plugin
language folder) installed in both admin and site
core language folders when creating a new
language, for them to function properly.

Yes, we could do without it for com_localise, but
would not that be easier for a casual Translator,
specially for someone editing manually?

>
>> # Version 1.6 pre-alpha // In fact, this is not the Joomla version
>> only. This becomes necessary when the Translation Team coordination
>> has to control the update of packs provided by the Translation Teams
>> when Joomla version is updated, as we can't control when a specific
>> ini has been updated or not. Can be # Version 1.6v1, v2 or # Version

>> 1.6.1, 1.6.1v1, etc.* 1.6 or 1.6.1 are related to the Joomla version,

>> v1 or v2 etc. to the language pack version.
>
>I can live with the Joomla version, but why couldn't the Id tag (the
>revision number) serve the same role as the "v" numbers. Or, I am not
>understanding why the "v" numbers are significant.

# id meta is only created/used by SVN working
people and most translators don't use it.
This means that the SVN version as well as the
date are 99% of the time incorrect in the id.
In fact they would only be correct if each
language was recreated from scratch based on the
original reference file
It is also true for 3pd ini files.
The "v" version is used when users/translators
discover that a Translation pack is missing a
string or a string has been wrongly translated
-after releasing their pack. In this case the TT
makes a new pack and states the v in the pack
name. This adds to figure out which version of
the language pack one deals with as it is shown
nowhere after the language has been installed.
This will show in com_localise UI.

>
>> # Desc Joomla! English(GB) // Used to know which language is concerned
>> and for which specific usage i.e. Jooma core or 3pd. For 3pd, the name
>> of extension should be added instead of Joomla! i.e. # Desc
>> Mycomponent English(GB). This provides for easier identification of
>> the file when SVN is not used i.e. when edited manually or through
>> com_localise.
>
>I have a problem with this being different for core and 3pds - that's
>confusing. But why for core do you need the language name when it can
>be looked up in the XML file. The file name also tells you what the
>language is. For 3pd's, the file name also tells you the language and
>where it applies to (which extension). Just don't like the idea of
>doubling up information that we already have, that's all.

Understand your concern. Redundancy is to avoid when not necessary.
This meta is to cope with Translation Policy
http://community.joomla.org/translations/typical-language-file-headers.html
to replace
# Joomla! [full language name in clear] Translation
We need to have this field present in
com_localise to add the Language Name and
"Translation" term when necessary
It would also be used for 3pds inis and I think
it is not confusing, it takes of confusion by
adding information.

The older Translation Manager was very confusing
in its UI, could not differentiate core and
non-core files, did not have to deal with the new
implementation of local language folders, did not
make any other install packs than core ones.
If we implement these metas, we not only make for
com_localise a user and feature friendly UI but
also help basic users know precisely what is what
when they open an ini file. And this makes it
easier for all. How many times did I have to ask
on the forums which ini file and where it was in
Joomla when a user was asking help?

JM

--
Merci de ne pas renvoyer de pièces attachées automatiquement.
------------------
Jean-Marie Simonet/infograf

info...@orange.fr
http://www.info-graf.fr

[infograf768]

I bump this one after a partial demo (com_localise is still WIP) to
Andrew.
I think we can do whatever we need to comply with Policy regarding the
translated inis, even if the needed metas are not present in the en-GB
files.
After all, this is what we already ask TTs to do.

We still need though to differentiate Core ini files from any other
ini files, as I think I demonstrated to Andrew.
This is not only of use for filtering/translating, but also to make
packages, any kind of packages necessary.

We have only 2 ways to do that:

1. Add the meta # Core
This is the easiest. It is independant from the type of release
(light, full, SDK).
It does not require an update when ini files are added or taken of
from Core (this has happened quite a few times for 1.5 this year).

2. Work with an xml/txt file listing all present core inis in a
release.

A. That is also easy if that xml file is present in the official
release and updated in function of the changes.
That list could be part of manifests/packages/joomla.xml or a separate
file. It requires updating by JBS when necessary and not just before
release.

B. It becomes much more complex if the list is not in the release/SVN.
In this case, the list has to be present in com_localise folder or
dependant and updated through an internet connexion.
A bit as we do for the helpsites-15.xml, but automatically, when
loading com_localise.
It means that com_localise has to link to the Net and find that file
somewhere.
It also means someone has to update that file when necessary.
I.e. follow every move in jbs and update at the precise time a change
is done.

I hope this is clear to all and that a decision can be taken.
Please contact me if you want a live demo of com_localise.
JM

PS: we do understand that com_localise may have to be presented as a
separate package and not included in the official release, was it only
because of its mere weight.
We are willing to make a separate specific extension that would permit
editing/creating xx-XX.override.ini only, as part of core, if asked
to.

> This meta is to cope with Translation Policyhttp://community.joomla.org/translations/typical-language-file-header...

> ...
>
> read more »

[Louis Landry]

Hi JM,

Who is developing this extension?  Can you ask them to join us on this list to help talk through some of this... it would certainly help I think.

I think it would be relatively easy to get the "core" INI files from the main language XML file and would not necessitate the adding of new meta to all the language files.  We certainly need to be keeping up with which language files are added or removed with respect to the core distribution and should update that XML file as necessary.  That is something we should be doing anyway.

I'm glad to see work being done on a tool to help the localization/translation process :)

- Louis

--
Development Coordinator
Joomla! ... because open source matters.
http://www.joomla.org

[JM Simonet]

Hello Louis
As you can see below, the main developper is Christophe Demko and I will indeed ask him to post here.
http://joomlacode.org/gf/project/com_localise/scmsvn/?action=browse&path=%2Ftrunk%2Fadministrator%2Fcomponents%2Fcom_localise%2F

(As you may imagine, though, what I wrote above is the result of our discussions, not my own solitary comments. ;) )

If a list of the files is added in an xml file, -which is indeed the second solution we proposed above-, is your idea to add this list in the en-GB.xml or as a separate xml of the same type we do when making packages, i.e. an install.xml?
If the last case, we could change its name to en-GB_install.xml for example and it would be present in each en-GB folder.
The reason I ask this is that when we make core packages, we have to mimic the original core en-GB folders.

Concerning the inis, we can just add in the Translated inis the metas we need to comply with Translation policy depending on the type of core files, without using the # Core meta.

It is a pity though that we would not be able to present in com_localise UI, the version of the ini and its date, although we can create these concerning Translated languages. See attached screenshot.

JM

[Christophe Demko]

Hi to all,

Actually, I'm the main developer of com_localise.

JM Simonnet has decribed in perfect terms the problem

We need to know the core language files. Why?

1) com_localise will be used to create new language pack. One of the
first feature will be to create Joomla language pack. These packs
(site, admin, boths, install) will contain and will only contain
initial language files (those who are in the core)
2) com_localise will be used to create new language pack for third
party extensions. In these packs, core language files will be
excluded. Only third party language files could be members of these
packs
3) com_localise is used through a UI. It's very convenient for the
users to know the type of languages files (core or not).

For my point of view the best solution is to extract the list of core
language files from Joomla initial installation.
a) either from an xml file
b) either from each of the en-GB ini files (including a # core
comment)

With these solutions, we are sure that this list is uptodate.

From a developer view, the "best" solution would be the a) one.
Actually we have chose the b) one because we were not sure to get this
xml file.

[infograf768]

Sorry to bump again folks, but we do need a decision on this.

[Andrew Eddie]

The short answer to one of the problems is add a <files> tag to both
of the en-GB.xml files and list all of the core ini files that are
shipped with Joomla in that. That dispenses with the core markup in
the ini files themselves. Just parse the main xml file and you know
what to package. This can be then applied consistently by your tool
for any case.

Regards,
Andrew Eddie
http://www.theartofjoomla.com - the art of becoming a Joomla developer




2009/5/8 infograf768 <infog...@gmail.com>:

[infograf768]

Thanks for your reply.
We can prepare the patch.
How do you want it?
1. place of the <files></files>
between </metadata> and <params /> or between <params \> and </
metafile> ?
2. Naming of files
full name : en-GB.com_members.ini
without suffix : en-GB.com_members
without suffix & prefix : com_members
?

On 13 May, 09:24, Andrew Eddie <mambob...@gmail.com> wrote:
> The short answer to one of the problems is add a <files> tag to both
> of the en-GB.xml files and list all of the core ini files that are
> shipped with Joomla in that.  That dispenses with the core markup in
> the ini files themselves.  Just parse the main xml file and you know
> what to package.  This can be then applied consistently by your tool
> for any case.
>
> Regards,

> Andrew Eddiehttp://www.theartofjoomla.com- the art of becoming a Joomla developer
>
> 2009/5/8 infograf768 <infograf...@gmail.com>:

[Andrew Eddie]

2009/5/13 infograf768 <infog...@gmail.com>:

>
> Thanks for your reply.
> We can prepare the patch.
> How do you want it?
> 1. place of the <files></files>
> between </metadata> and <params /> or between <params \> and </
> metafile> ?

Just look at any extensions manifest. Placement is not a big issue.
It could go after the <description> tag. The <params> tag typically
goes after it but it doesn't really matter.

> 2. Naming of files
> full name : en-GB.com_members.ini
> without suffix : en-GB.com_members
> without suffix & prefix : com_members
> ?

Full file names

<files>
<filename>en-GB.com_members.ini</file>
...
</files>

Thanks.

Andrew

[JM Simonet]

Thanks.
New xml files sent to Sam to commit.
;)