You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@directory.apache.org by Javier Estrada <ja...@verizon.net> on 2012/02/01 19:29:29 UTC
[DOC] Interested in documenting the API.
What is the process to help in documenting the API?
--Javier
Re: [DOC] Interested in documenting the API.
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
On 3 févr. 2012, at 18:59, Javier Estrada wrote:
> Yes. A JIRA would be fine.
Here it is, DIRSTUDIO-766 (Localize Apache Directory Studio in Spanish).
https://issues.apache.org/jira/browse/DIRSTUDIO-766
Thanks,
Pierre-Arnaud
> -----Original Message-----
> From: pajbam@gmail.com [mailto:pajbam@gmail.com] On Behalf Of Pierre-Arnaud Marcelot
> Sent: Friday, February 03, 2012 8:50 AM
> To: users@directory.apache.org; javier.estrada4@verizon.net
> Subject: Re: [DOC] Interested in documenting the API.
>
> On Fri, Feb 3, 2012 at 5:24 PM, Javier Estrada
> <ip...@gmail.com> wrote:
>> Where do I start with this localization effort for Studio?
>
> All (most of) the strings used in the UI of Studio are already
> externalized into properties files in Studio's repository [1].
> The default files ('messages.properties' or 'plugin.properties') are
> in english and aside them you also find one file per translation
> ('messages_fr.properties' or 'plugin_fr.properties' for the french
> translation).
>
> If you want to add spanish translation, you'll need to add new
> specific files ('messages_es.properties' or 'plugin_es.properties')
> and translate the
> strings into them.
>
> The best way to do this is to duplicate the english file, rename it
> and then start localizing.
> In the case where the translated string is the same in both langages,
> please remove it from the translation, the english version will be
> used by default (this is done to avoid duplication).
>
> Tell me if you need anything else.
>
> Do you want me to create a dedicated JIRA in Studio's project for you
> to send patches?
>
> Thanks,
> Pierre-Arnaud
>
> [1] - http://svn.apache.org/repos/asf/directory/studio/trunk/
RE: [DOC] Interested in documenting the API.
Posted by Javier Estrada <Ja...@cassidiancommunications.com>.
Yes. A JIRA would be fine.
-----Original Message-----
From: pajbam@gmail.com [mailto:pajbam@gmail.com] On Behalf Of Pierre-Arnaud Marcelot
Sent: Friday, February 03, 2012 8:50 AM
To: users@directory.apache.org; javier.estrada4@verizon.net
Subject: Re: [DOC] Interested in documenting the API.
On Fri, Feb 3, 2012 at 5:24 PM, Javier Estrada
<ip...@gmail.com> wrote:
> Where do I start with this localization effort for Studio?
All (most of) the strings used in the UI of Studio are already
externalized into properties files in Studio's repository [1].
The default files ('messages.properties' or 'plugin.properties') are
in english and aside them you also find one file per translation
('messages_fr.properties' or 'plugin_fr.properties' for the french
translation).
If you want to add spanish translation, you'll need to add new
specific files ('messages_es.properties' or 'plugin_es.properties')
and translate the
strings into them.
The best way to do this is to duplicate the english file, rename it
and then start localizing.
In the case where the translated string is the same in both langages,
please remove it from the translation, the english version will be
used by default (this is done to avoid duplication).
Tell me if you need anything else.
Do you want me to create a dedicated JIRA in Studio's project for you
to send patches?
Thanks,
Pierre-Arnaud
[1] - http://svn.apache.org/repos/asf/directory/studio/trunk/
Re: [DOC] Interested in documenting the API.
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
On Fri, Feb 3, 2012 at 5:24 PM, Javier Estrada
<ip...@gmail.com> wrote:
> Where do I start with this localization effort for Studio?
All (most of) the strings used in the UI of Studio are already
externalized into properties files in Studio's repository [1].
The default files ('messages.properties' or 'plugin.properties') are
in english and aside them you also find one file per translation
('messages_fr.properties' or 'plugin_fr.properties' for the french
translation).
If you want to add spanish translation, you'll need to add new
specific files ('messages_es.properties' or 'plugin_es.properties')
and translate the
strings into them.
The best way to do this is to duplicate the english file, rename it
and then start localizing.
In the case where the translated string is the same in both langages,
please remove it from the translation, the english version will be
used by default (this is done to avoid duplication).
Tell me if you need anything else.
Do you want me to create a dedicated JIRA in Studio's project for you
to send patches?
Thanks,
Pierre-Arnaud
[1] - http://svn.apache.org/repos/asf/directory/studio/trunk/
Re: [DOC] Interested in documenting the API.
Posted by Javier Estrada <ip...@gmail.com>.
Where do I start with this localization effort for Studio?
>> We've already gone to the localization road with Apache Directory Studio (which supports English, German and French) and our experience is that you really want to that at the end of the development.
>>
>> BTW, if you're willing to provide some help localizing Apache Directory Studio in Spanish, feel free to ask where to start… ;)
Re: [DOC] Interested in documenting the API.
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
On 2 févr. 2012, at 17:22, Javier Estrada wrote:
> I have up to chapter three in fixing typos and grammar and would like
> to get some feedback before I do some more. I first need to get
> acquainted with the API details to be more effective.
Great! :)
> Here are some of the general fixes:
> - Capital wording in titles (e.g., "This is a title" becomes "This is
> a Title" ).
> - General punctuation corrections (elimination of extra commas, adding
> periods at the end of sentences and lists.
> - Replacing "expose(s)" for "present(s)" or "provide(s)". For
> example, "This chapter exposes" becomes "This chapter presents...". By
> the way, in Spanish it's very common to use expose, too.
> - General replacement of it's for it is for more formal writing.
Sounds like great rules to me.
> I'll push this to JIRA shortly.
>
> Another question I have is if the documentation can be
> internationalized. My fist language is Spanish and I can provide a
> very good translation if desired.
At some point, when the documentation will be sufficiently advanced, reviewed and stabilized, we might indeed want to localize it.
But, it really needs to be done at the end of the process, when we're sure about the english version first.
We've already gone to the localization road with Apache Directory Studio (which supports English, German and French) and our experience is that you really want to that at the end of the development.
BTW, if you're willing to provide some help localizing Apache Directory Studio in Spanish, feel free to ask where to start… ;)
You'd be more than welcome again.
Regards,
Pierre-Arnaud
Re: [DOC] Interested in documenting the API.
Posted by Javier Estrada <ip...@gmail.com>.
I have up to chapter three in fixing typos and grammar and would like
to get some feedback before I do some more. I first need to get
acquainted with the API details to be more effective.
Here are some of the general fixes:
- Capital wording in titles (e.g., "This is a title" becomes "This is
a Title" ).
- General punctuation corrections (elimination of extra commas, adding
periods at the end of sentences and lists.
- Replacing "expose(s)" for "present(s)" or "provide(s)". For
example, "This chapter exposes" becomes "This chapter presents...". By
the way, in Spanish it's very common to use expose, too.
- General replacement of it's for it is for more formal writing.
I'll push this to JIRA shortly.
Another question I have is if the documentation can be
internationalized. My fist language is Spanish and I can provide a
very good translation if desired.
= = =
Re: [DOC] Interested in documenting the API.
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 2/2/12 2:45 PM, Javier Estrada wrote:
> Thx for all the info. I'm installing Tortoise SVN on Windows and will
> check (out) the docs. Once I have a proposal for change I'll push it
> for review.
>
Great !
I have created a JIRA : https://issues.apache.org/jira/browse/DIRAPI-74
Just attach your patches there (please attach many little modifications
rather than one big shot : it will be easier to integrate, easier to
review, and also easier to track the progression)
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: [DOC] Interested in documenting the API.
Posted by Javier Estrada <ip...@gmail.com>.
Thx for all the info. I'm installing Tortoise SVN on Windows and will
check (out) the docs. Once I have a proposal for change I'll push it
for review.
Re: [DOC] Interested in documenting the API.
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 2/1/12 7:29 PM, Javier Estrada wrote:
> What is the process to help in documenting the API?
Hi !
First it would be a pleasure to have some help in this area, it's really
needed...
We us a Confluence based format for documentation. Everything is in the
subproject ldap-api-manuals (in
http://svn.apache.org/viewvc/directory/documentation/). Th best is to
checkout the project :
svn co http://svn.apache.org/viewvc/directory/documentation/ldap-api-manuals
Then all the files are text files, and can be modified and 'diffed'. For
instance, if you add some new file, or modify an existing one, when you
are done, you just have to do :
cd ldap-api-manuals
svn diff . > modifications.txt
and to add the file to a JIRA (I can create one if needed).
If you want any information or direction that can help, you can contact
us on IRC (channel #apache-directory-dev).
Thanks a lot !
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: [DOC] Interested in documenting the API.
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
Hi Javier,
Thanks for your proposal. Any help is more than welcome. :)
The API user's guide visible at this URL [1] has been transferred from wiki pages edited online via Confluence to a text-based (in the Confluence wiki format) Maven project in Subversion [2] which allows us to generate HTML *and* PDF output using Docbook (generated via the 'mvn site').
As Alex explained, the best way to interact with us is to propose patches for this Maven project has attachments of a JIRA issue.
If you're not that familiar with Maven, the Confluence text format or the other stuff we use in that project, a simple text file can be enough (we can handle the formatting afterwards).
Feel free to ask if you need any additional information.
Regards,
Pierre-Arnaud
[1] - http://directory.apache.org/api/user-guide.html
[2] - https://svn.apache.org/repos/asf/directory/documentation/ldap-api-manuals/trunk
On 1 févr. 2012, at 19:29, Javier Estrada wrote:
> What is the process to help in documenting the API?
>
> --Javier
Re: [DOC] Interested in documenting the API.
Posted by Alex Karasulu <ak...@apache.org>.
There really is no set process other than document something and provide a
document or patch in JIRA whether it's internal docs or does for a manual
respectively.
We like people who like to document stuff :-).
Thanks man,
Alex
On Wed, Feb 1, 2012 at 8:29 PM, Javier Estrada
<ja...@verizon.net>wrote:
> What is the process to help in documenting the API?
>
> --Javier
>
--
Best Regards,
-- Alex